Primer React v35 RC - Technical Preview #1918

rezrah · 2022-03-02T13:12:21Z

rezrah
Mar 2, 2022
Maintainer

The Primer team are excited to share some major updates that will arrive in v35 of @primer/react.

This technical preview will cover:

What is coming in v35
How to try v35 yourself today
When v35 will ship
Our long-term strategy for breaking-changes, deprecations, LTS and EoL

Overview

Primer React is now used in many high-profile projects, both internally at GitHub and in the wider public. Our approach to managing releases will evolve to match the expectations of our community. This technical preview will provide early access to the next major release of @primer/react and provide insight into how you can prepare for an eventual upgrade.

The Primer team will look to publish release candidates and technical previews ahead of major updates to the library going forward. The intention here is to batch major changes into fewer releases, thereby offering more longer-term stability to active major versions and ensure that the community have adequate time to prepare for future breaking changes.

⚠️ This technical preview is intended to provide early notice for many upcoming breaking changes. Please read carefully to understand how this may impact you.

🔧 Try it today

You can try v35 RC today on the next-major release channel.

npm install @primer/react@next-major

This release candidate is available for preview and feedback purposes only. We don’t recommend using this in production.

OR

Try @primer/react@v35 on StackBlitz ⚡

📆 Release schedule

2 March	Public beta for v35 on the "next-major" release channel
7 March	Close public beta
8 March	General Availability on the "Latest" release channel

Minor and Patch updates to v34 will continue to roll out independently to v35

✨ New in `v35`

⚠️ Breaking changes

v35 will contain a handful of breaking changes.

Graduations

PageLayout

Deprecations

All components marked for deprecation will:

Move immediately into a new deprecated bundle.
Receive limited ongoing support, as the team shifts focus to graduated versions.
Be officially marked as end-of-life (EOL) after 6 months of the initial deprecation.
Be removed entirely from the library after its EOL date has elapsed.

Read more on our deprecations process here.

Summary of changes

Are you using any of the components below? Skip to the relevant section below to learn about what's changing.

ActionList
ActionMenu
BorderBox
Button
Dropdown
DropdownMenu
FormGroup, InputField and ChoiceInputField
Grid
Position
SelectMenu

🔗 ActionList

The new ActionList will ship with a composable API and improved accessibility, including better support for assistive technologies and keyboard users.

Before (v34)

After (v35)

import {ActionList} from '@primer/react/ActionList';

<ActionList
  items={[
    {text: 'New file'},
    {text: 'Copy link'},
    {text: 'Edit file'},
    ActionList.Divider,
    {text: 'Delete file', variant: 'danger'}
  ]}
/>

import {ActionList} from '@primer/react/ActionList';

<ActionList>
  <ActionList.Item>
    New file
  </ActionList.Item>
  <ActionList.Item>
    Copy link
  </ActionList.Item>
  <ActionList.Item>
    Edit file
  </ActionList.Item>
  <ActionList.Divider />
  <ActionList.Item variant="danger">
    Delete file
  </ActionList.Item>
</ActionList>

Migration steps for ActionList
Upgrade to the new `ActionList` by referring to the examples in our documentation. or Continue using the deprecated `ActionList` : import { ActionList } from '@primer/react/deprecated'; Alternatively, try our `codemod` to change your `import` statements automatically ⚡

🔗 ActionMenu

The new ActionMenu will ship with a composable API, visual updates and accessibility fixes built on top of ActionList and Button, which will also be included in v35.

Before (v34)

After (v35)

<ActionMenu
  anchorContent="Menu"
  onAction={fn}
  items={[
    {text: 'New file'},
    {text: 'Copy link'},
    {text: 'Edit file'},
    ActionMenu.Divider,
    {text: 'Delete file', variant: 'danger'}
  ]}
  overlayProps={{width: 'small'}}
/>

<ActionMenu>
  <ActionMenu.Button>Menu</ActionMenu.Button>
  <ActionMenu.Overlay width="small">
    <ActionList>
      <ActionList.Item onSelect={fn}>New file</ActionList.Item>
      <ActionList.Item>Copy link</ActionList.Item>
      <ActionList.Item>Edit file</ActionList.Item>
      <ActionList.Divider />
      <ActionList.Item variant="danger">Delete file</ActionList.Item>
    </ActionList>
  </ActionMenu.Overlay>
</ActionMenu>

Migration steps for ActionMenu
Upgrade to the new `ActionMenu` by referring to the examples in our documentation. or Continue using the deprecated `ActionMenu` : import { ActionMenu } from '@primer/react/deprecated'; Alternatively, try our `codemod` to change your `import` statements automatically ⚡

🔗 Button

Button will be replaced with a newer, more accessible equivalent that includes an improved API for better ergonomics.

New features include improvements to size handling and built-in support for leading and trailing visuals.

Before (v34)

After (v35)

/*
import {
  ButtonPrimary, ButtonInvisible, ButtonOutline, ButtonDanger
} from "@primer/react";
*/

<>
  <ButtonPrimary>
    Primary Button
  </ButtonPrimary>
  
  <ButtonInvisible>
    Invisible Button
  </ButtonInvisible>
  
  <ButtonOutline>
    Outline Button
  </ButtonOutline>
  
  <ButtonDanger>
    Danger Button
  </ButtonDanger>
</>

/*
import {
  Button
} from "@primer/react";
*/

<>
  <Button variant="primary">
    Primary Button 
  </Button>
  
  <Button variant="invisible">
    Invisible Button 
  </Button>
  
  <Button variant="outline">
    Outline Button 
  </Button>
  
  <Button variant="danger">
    Danger Button 
  </Button>
</>

Migration steps for Button
Upgrade to the new `Button` by referring to the examples in our documentation. or Continue using the deprecated `Button` : import { Button } from "@primer/react/deprecated" Alternatively, try our `codemod` to change your `import` statements automatically ⚡

🔗 DropdownMenu

DropdownMenu and DropdownMenu2 are being deprecated in favour of ActionMenu.

Before (v34)

After (v35)

const fieldTypes = [
  {leadingVisual: TypographyIcon, text: 'Text'},
  {leadingVisual: NumberIcon, text: 'Number'},
];

const [selectedItem, setSelectedItem] = React.useState()

<DropdownMenu
  renderAnchor={({children, ...anchorProps}) => (
    <ButtonInvisible {...anchorProps}>
      {children}
    </ButtonInvisible>
  )}
  placeholder="Select a field type"
  items={fieldTypes}
  selectedItem={selectedItem}
  onChange={() => setSelectedIndex(index)}
/>

const fieldTypes = [
  {icon: <TypographyIcon/>, name: 'Text'},
  {icon: <NumberIcon/>, name: 'Number'},
];

const [selectedItem, setSelectedItem] = React.useState()

<ActionMenu>
  <ActionMenu.Button>{selectedItem ? selectedItem.name : 'Select a field type'}</ActionMenu.Button>
  <ActionMenu.Overlay>
     <ActionList selectionVariant="single">
      {fieldTypes.map(field => (
        <ActionList.Item onSelect={() => setSelectedItem(field)} key={field.name}>
           <ActionList.LeadingVisual>{field.icon}</ActionList.LeadingVisual>
           {field.name}
         </ActionList.Item>
     <ActionList>
  </ActionMenu.Overlay>
<ActionMenu>

Migration steps for DropdownMenu
Upgrade to the new `ActionMenu` by referring to the examples in our documentation. or Continue using the deprecated `DropdownMenu` : import { DropdownMenu } from '@primer/react/deprecated'; Alternatively, try our `codemod` to change your `import` statements automatically ⚡

🔗 PageLayout

PageLayout is now being graduated from the drafts bundle to the main bundle.

Use PageLayout by referring to the examples in our documentation.

Before (v34)	After (v35)
import {PageLayout} from "@primer/react/drafts"	import {PageLayout} from "@primer/react"

🔗 Label

The Label component has been updated to align with Primer ViewComponents' Label component. Now the React component is consistent with ViewComponents.

Major changes in the new Label component:

No more medium size - only small and large
Labels are outlined by default, so the outline prop has been removed
Custom text and background colors are discouraged, but still possible via the sx prop

If you were using the Label component to render issue/PR labels, use the IssueLabelToken component instead.

Arbitrary label

Before (v34)

After (v35)

import {Label} from "@primer/react";

<Label outline>default</Label>
<Label 
  variant="small" 
  outline sx={{
    borderColor: 'danger.emphasis', 
    color: 'danger.fg'
  }}
>
  danger
</Label>

import {Label} from "@primer/react";

<Label>default</Label>
<Label 
  size="small" 
  variant="danger"
>
  danger
</Label>

Issue label

Before (v34)

After (v35)

import {Label} from "@primer/react";

<Label 
  variant="medium" 
    sx={{
      bg: '#FFF06C', 
      color: '#24292E', 
      m: 1
    }}
>
  documentation
</Label>

import {IssueLabelToken} from "@primer/react";

<IssueLabelToken 
  text="documentation" 
  fillColor="#FFF06C" 
/>

Migration steps for Label
Upgrade to the new `Label` by referring to the Label and IssueTokenLabel examples in our documentation. or Continue using the deprecated `Label` : import { Label } from '@primer/react/deprecated'; Alternatively, try our `codemod` to change your `import` statements automatically ⚡

🔗 FormGroup, InputField and ChoiceInputField

The FormControl component will be used to deprecate the FormGroup, InputField, and ChoiceInputField components. It has the ability to render contextual content with your inputs: labels, validation statuses, captions. It also handles the ARIA attributes that make the form controls accessible to assistive technology.

Before (v34)

After (v35)

import {
    FormGroup, 
    Checkbox,
    TextInput
} from "@primer/react";


<FormGroup>
    <FormGroup.Label 
      htmlFor="example-text"
    >
      Example text
    </FormGroup.Label>
    <TextInput id="example-text" />
</FormGroup>

// OR

<InputField>
    <InputField.Label>
      Example text
    </InputField.Label>
    <TextInput />
</InputField>

// OR

<ChoiceInputField>
    <ChoiceInputField.Label>
      Example text
    </ChoiceInputField.Label>
    <Checkbox />
</ChoiceInputField>

import {
    FormControl, 
    Checkbox, 
    TextInput
} from "@primer/react";


<FormControl>
  <FormControl.Label>
    Example text
  </FormControl.Label>
  <TextInput />
</FormControl>

// OR

<FormControl>
  <FormControl.Label>
    Example text
  </FormControl.Label>
  <Checkbox />
</FormControl>

import {InputField} from "@primer/react";

<InputField>
    <InputField.Label>Example text</InputField.Label>
    <TextInput />
</InputField>

import {FormControl} from "@primer/react";

<FormControl>
  <FormControl.Label>Example Text</FormControl.Label>
  <TextInput />
</FormControl>

Migration steps to FormControl
Upgrade to the new `FormControl` component by referring to the examples in our documentation. or Continue using the deprecated `FormGroup`, `ChoiceInputField` or `InputField` : import { FormGroup, ChoiceInputField, InputField } from "@primer/react/deprecated"

🔗 SelectMenu

SelectMenu will move from the main bundle into the deprecated bundle.

We recommend using ActionMenu as a longer-term replacement.

Before (v34)

After (v35)

import {SelectMenu} from "@primer/react"

<SelectMenu>
  <Button as="summary">
    Projects
  </Button>
  <SelectMenu.Modal>
    <SelectMenu.Header>
      Projects
    </SelectMenu.Header>
    <SelectMenu.List>
      <SelectMenu.Item href="#">
        Primer React bugs
      </SelectMenu.Item>
      <SelectMenu.Item href="#">
        Primer React roadmap
      </SelectMenu.Item>
      <SelectMenu.Item href="#">
        Project 3
      </SelectMenu.Item>
      <SelectMenu.Item href="#">
        Project 4
      </SelectMenu.Item>
    </SelectMenu.List>
  </SelectMenu.Modal>
</SelectMenu>

import {ActionMenu, ActionList} from "@primer/react"

<ActionMenu>
  <ActionMenu.Button>
    Projects
  </ActionMenu.Button>
  <ActionMenu.Overlay>
    <ActionList showDividers>
      <ActionList.Group title="Projects">
        <ActionList.Item>
          Primer React bugs
        </ActionList.Item>
        <ActionList.Item>
          Primer React roadmap
        </ActionList.Item>
        <ActionList.Item>
          Project three
        </ActionList.Item>
        <ActionList.Item>
          Project four
        </ActionList.Item>
      </ActionList.Group>
    </ActionList>
  </ActionMenu.Overlay>
</ActionMenu>

Migration steps to SelectMenu
Upgrade from `SelectMenu` to `ActionMenu` by referring to the example above or our documentation. or Continue using the deprecated `SelectMenu`: import { SelectMenu } from "@primer/react/deprecated" Alternatively, try our `codemod` to change your `import` statements automatically ⚡

🔗 Dropdown

Dropdown will move from the main bundle into the deprecated bundle.

We recommend using ActionMenu as a longer-term replacement.

Before (v34)

After (v35)

import {Dropdown} from "@primer/react"

<Dropdown>
  <Dropdown.Button>
    Select a field type
  </Dropdown.Button>
  <Dropdown.Menu>
    <Dropdown.Item>Text</Dropdown.Item>
    <Dropdown.Item>Number</Dropdown.Item>
    <Dropdown.Item>Date</Dropdown.Item>
  </Dropdown.Menu>
</Dropdown>

import {ActionMenu, ActionList} from "@primer/react"

<ActionMenu>
  <ActionMenu.Button>
    Select a field type
  </ActionMenu.Button>
  <ActionMenu.Overlay>
    <ActionList selectionVariant="single">
        <ActionList.Item>
          Text  
        </ActionList.Item>
        <ActionList.Item>
          Number  
        </ActionList.Item>
        <ActionList.Item>
          Date  
        </ActionList.Item>
    </ActionList>
  </ActionMenu.Overlay>
</ActionMenu>

Migration steps to SelectMenu
Upgrade from `Dropdown` to `ActionMenu` by referring to the example above or our documentation. or Continue using the deprecated `Dropdown`: import { Dropdown } from "@primer/react/deprecated" Alternatively, try our `codemod` to change your `import` statements automatically ⚡