Skip to content

Update component docs (Header, Radio, Checkbox, Heading, Label, LabelGroup) #1708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 17 commits into from
Dec 20, 2021
Merged

Update component docs (Header, Radio, Checkbox, Heading, Label, LabelGroup) #1708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
f356d91
docs: converted markdown props to use prop table component
rezrah Dec 9, 2021
b9ccc23
docs: converted radio markdown props to use prop table component
rezrah Dec 9, 2021
f27b94a
docs: converted header markdown props to use prop table component
rezrah Dec 9, 2021
84bf8e7
docs: converted heading markdown props to use prop table component
rezrah Dec 9, 2021
04bbdf4
docs: converted label markdown props to use prop table component
rezrah Dec 9, 2021
68e5ba0
docs: converted labelgroup markdown props to use prop table component
rezrah Dec 9, 2021
58b8840
Merge branch 'main' of github.com:primer/react into docs/convert-prop…
rezrah Dec 9, 2021
e130ede
docs: address PR feedback
rezrah Dec 10, 2021
6c06832
docs: address PR feedback
rezrah Dec 10, 2021
dcc990d
docs: address PR feedback for checkbox
rezrah Dec 10, 2021
8161211
Merge branch 'main' of github.com:primer/react into docs/convert-prop…
rezrah Dec 10, 2021
5364786
docs: add component status checklist to label
rezrah Dec 10, 2021
1098cb1
docs: add component status checklist to labelgroup
rezrah Dec 10, 2021
5e4c0e4
docs: add component status checklist to heading + header
rezrah Dec 10, 2021
d32dc87
docs: add guard for refType in PropsTableBasePropRows
rezrah Dec 10, 2021
2345eb6
docs: add guard for refType in PropsTableBasePropRows
rezrah Dec 10, 2021
ff10c7c
chore: fix merge conflicts
rezrah Dec 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 57 additions & 20 deletions docs/content/Checkbox.md → docs/content/Checkbox.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,24 @@
---
componentId: checkbox
title: Checkbox
description: Use checkboxes to toggle between checked and unchecked states in a list or as a standalone form field
status: Alpha
source: https://github.com/primer/react/blob/main/src/Checkbox.tsx
storybook: '/react/storybook?path=/story/forms-checkbox--default'
componentId: checkbox
---

import {ComponentChecklist} from '../src/component-checklist'

## Examples

<Note variant="warning">

**Use [ChoiceInputField](/ChoiceInputField) to display an accessible checkbox form field**. 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 do use this component to build a custom checkbox, it should always be accompanied by a corresponding `<label>` to improve support for assistive technologies.

</Note>

## Default example

The `Checkbox` component can be used in controlled and uncontrolled modes.

```jsx live
Expand Down Expand Up @@ -53,10 +52,11 @@ The `Checkbox` component can be used in controlled and uncontrolled modes.
```

<Note variant="warning">
Checkbox components should always be accompanied by a corresponding label to improve support for assistive technologies.
Checkbox components should always be accompanied by a corresponding label to improve support for assistive
technologies.
</Note>

## Indeterminate example
## 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.

Expand Down Expand Up @@ -95,22 +95,59 @@ An `indeterminate` checkbox state should be used if the input value is neither t
</>
```

## Component props

Native `<input>` attributes are forwarded to the underlying React `input` component and are not listed below.

| Name | Type | Default | Description |
| :------------- | :---------- | :-------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| checked | Boolean | undefined | Optional. Modifies true/false value of the native checkbox |
| defaultChecked | Boolean | undefined | Optional. Checks the input by default in uncontrolled mode |
| onChange | ChangeEvent | undefined | Optional. A callback function that is triggered when the checked state has been changed. |
| disabled | Boolean | undefined | Optional. Modifies the native disabled state of the native checkbox |
| indeterminate | Boolean | undefined | Optional. Applies an [indeterminate](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#attr-indeterminate) state to the checkbox |

## Component status
## Props

<PropsTable>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading of prop tables is usually the name of the component:

Suggested change
<PropsTable>
### Checkbox
<PropsTable>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example heading in the Issue description here shows it as Props, which feels sensible given the content it describes... or am I misunderstanding this? What was the reasoning behind repeating the component name here?

<PropsTableRow
name="checked"
type="boolean"
description="Modifies true/false value of the native checkbox"
/>
<PropsTableRow
name="defaultChecked"
type="boolean"
description="Checks the input by default in uncontrolled mode"
/>
<PropsTableRow
name="onChange"
type="(event: React.ChangeEvent) => void"
description="A callback function that is triggered when the checked state has been changed"
/>
<PropsTableRow
name="disabled"
type="boolean"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this have a default value?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's an optional prop, so no. Or are you setting undefined explicitly?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to say this defaults tofalse?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's misrepresenting the data type, as false !== undefined. I think literally undefined would make sense, or to provide a way to clearly indicate it's optional the same way you do with required?

description="Modifies the native disabled state of the native checkbox"
/>
<PropsTableRow
name="indeterminate"
type="boolean"
defaultValue="false"
description={
<>
Applies an{' '}
<Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#attr-indeterminate">
indeterminate state
</Link>{' '}
to the checkbox
</>
}
/>
<PropsTableBasePropRows
elementType="input"
refType="HTMLInputElement"
passthroughPropsLink={
<Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#additional_attributes">
MDN
</Link>
}
/>

</PropsTable>

## Status

<ComponentChecklist
items={{
items={{
propsDocumented: true,
noUnnecessaryDeps: true,
adaptsToThemes: true,
Expand Down
62 changes: 43 additions & 19 deletions docs/content/Header.md → docs/content/Header.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
componentId: header
title: Header
description: Use the Header component to create a header that has all of its items aligned vertically with consistent horizontal spacing
status: Alpha
source: https://github.com/primer/react/blob/main/src/Header.tsx
componentId: header
---

Use the `Header` component to create a header that has all of its items aligned vertically with consistent horizontal spacing.

## Default example
## Examples

All items directly under the Header component should be a `Header.Item` component. Inside these components can be anything (text, forms, images...), and the `Header.Item` component will make sure these elements vertically align with each other.

Expand All @@ -27,7 +27,7 @@ All items directly under the Header component should be a `Header.Item` componen
</Header>
```

## Header with full-size item example
### With full-size item

```jsx live
<Header>
Expand All @@ -39,7 +39,7 @@ All items directly under the Header component should be a `Header.Item` componen
</Header>
```

## Header with links example
### With links

```jsx live
<Header>
Expand All @@ -55,25 +55,49 @@ All items directly under the Header component should be a `Header.Item` componen
</Header>
```

## Component props
## Props

### Header

| Name | Type | Default | Description |
| :--- | :---------------- | :-----: | :----------------------------------- |
| sx | SystemStyleObject | {} | Style to be applied to the component |
<PropsTable>
<PropsTableSxRow />
</PropsTable>

### Header.Item

| Name | Type | Default | Description |
| :--- | :---------------- | :-----: | :----------------------------------------- |
| full | Boolean | | stretches item to fill the available space |
| sx | SystemStyleObject | {} | Style to be applied to the component |
<PropsTable>
<PropsTableRow name="full" type="string" description="Stretches item to fill the available space" />
<PropsTableSxRow />
</PropsTable>

### Header.Link

| Name | Type | Default | Description |
| :--- | :---------------- | :-----: | :----------------------------------- |
| as | String | | sets the HTML tag for the component |
| href | String | | URL to be used for the Link |
| sx | SystemStyleObject | {} | Style to be applied to the component |
<PropsTable>
<PropsTableRow name="href" type="string" description="URL to be used for the Link" />
<PropsTableBasePropRows
elementType="a"
passthroughPropsLink={
<Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes">MDN</Link>
}
/>
</PropsTable>

## Status

<ComponentChecklist
items={{
propsDocumented: true,
noUnnecessaryDeps: true,
adaptsToThemes: true,
adaptsToScreenSizes: false,
fullTestCoverage: false,
usedInProduction: false,
usageExamplesDocumented: true,
designReviewed: false,
a11yReviewed: false,
stableApi: false,
addressedApiFeedback: false,
hasDesignGuidelines: false,
hasFigmaComponent: false
}}
/>
22 changes: 0 additions & 22 deletions docs/content/Heading.md
View file
Open in desktop

This file was deleted.

44 changes: 44 additions & 0 deletions docs/content/Heading.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: Heading
description: Use Heading to structure your content and provide an accessible experience for users of assistive technologies.
source: https://github.com/primer/react/blob/main/src/Heading.tsx
status: Alpha
componentId: heading
---

The Heading component will render an html `h2` tag without any default styling. Other heading level elements `h1-h6` are available through use of the `as` prop (see [System Props](/system-props) for additional explanation). Please reference the [w3 recommendations for headings](https://www.w3.org/WAI/tutorials/page-structure/headings/) to ensure your headings provide an accessible experience for screen reader users.

**Attention:** Make sure to include a valid heading element to render a Heading component other than `h2` (`<Heading as="h1">H1 Element</Heading>`).

## Example

```jsx live
<Heading sx={{fontSize: 1, mb: 2}}>H2 heading with fontSize={1}</Heading>
```

## Props

<PropsTable>
<PropsTableAsRow defaultElementType="h2" />
<PropsTableSxRow />
</PropsTable>

## Status

<ComponentChecklist
items={{
propsDocumented: true,
noUnnecessaryDeps: true,
adaptsToThemes: true,
adaptsToScreenSizes: false,
fullTestCoverage: true,
usedInProduction: false,
usageExamplesDocumented: true,
designReviewed: false,
a11yReviewed: false,
stableApi: false,
addressedApiFeedback: false,
hasDesignGuidelines: false,
hasFigmaComponent: false
}}
/>
50 changes: 0 additions & 50 deletions docs/content/Label.md
View file
Open in desktop

This file was deleted.

Loading