Skip to content

Update component docs to use PropsTable and ComponentChecklist #1701

Closed
@colebemis

Description

@colebemis

Problems

Goals

  • Use the new PropsTable component, to render prop documentation consistently across all component pages on https://primer.style/react
  • The props table should not reference internal types. For example, if you have a string union called Variants, you should show each string ('danger' | 'success' | 'warning')
  • Add a component status checklist to every component page

Consistency nice-to-haves ✨

  • Every component page should have source frontmatter that links to the source code for that component (example)
  • Every component page should have an Examples, Props, and Status heading (in that order)
  • The top of every component page should show how to import the component (example)
    import {Box} from '@primer/react'
    

Non-goals

The props API of many of our components could be improved. However, changing the props of any component is out of scope for this issue.

Example

An example of how to use PropsTable and ComponentChecklist in an .mdx file:

---
title: ExampleComponent
status: Alpha
---

...

## Props

<PropsTable>
  {/* normal prop */}
  <PropTableRow
    name="variant"
    type="'default' | 'danger'"
    defaultValue="'inset'"
    description={<>...use a string or JSX to describe this prop...</>}
  />

  {/* required prop */}
  <PropTableRow
    name="children"
    required={true}
    type="React.ReactNode"
    description="..."
  />

  {/* deprecated prop */}
  <PropTableRow
    name="scheme"
    deprecated
    type="'default' | 'danger'"
    defaultValue="'inset'"
    description={<>Use <InlineCode>variant</InlineCode> instead</>}
  />

  {/* sx prop */}
  <PropsTableSxRow />

  {/* as prop */}
  <PropsTablePassthroughProps
    defaultElementType="a"
  />

  {/* ref prop */}
  <PropsTablePassthroughProps
    elementType="a"
    isPolymorphic={true}
    refType="HTMLAnchorElement"
  />

  {/* passthrough props */}
  <PropsTablePassthroughProps
    elementType="a"
    isPolymorphic={true}
    passthroughPropsLink={
      <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes">MDN</Link>
    }
  />
    
  {/* base props (combines sx, as, ref, and passthrough props) */}
  <PropsTableBasePropRows
    elementType="a"
    isPolymorphic={true}
    refType="HTMLAnchorElement"
    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: true,
    fullTestCoverage: true,
    usedInProduction: true,
    usageExamplesDocumented: true,
    hasStorybookStories: true
    designReviewed: null,
    a11yReviewed: null,
    stableApi: false,
    addressedApiFeedback: false,
    hasDesignGuidelines: null,
    hasFigmaComponent: null
  }}
/>

Components

👋 If you want to update any of the pages listed below, add your username next to the component name so we can avoid duplicating effort

  • ActionList
  • ActionList v2
  • ActionMenu
  • ActionMenu v2
  • AnchoredOverlay
  • Autocomplete @mperrotti
  • Avatar
  • AvatarPair
  • AvatarStack
  • BorderBox
  • Box
  • BranchName
  • Breadcrumbs
  • Button @mperrotti
  • CircleBadge
  • CircleOcticon
  • CounterLabel @mperrotti
  • Details
  • Dialog
  • Dialog v2
  • Dropdown
  • DropdownMenu
  • FilteredSearch
  • FilterList
  • Flash
  • Flex
  • FormGroup

☝️ @colebemis doing above unless indicated otherwise


👇 @rezrah doing below unless indicated otherwise

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions