Admin UI → Shoreline migration

[lucasaarcoverde]

Migration

In this documentation you can find information about what changed from @vtex/admin-ui@0.137.x to @vtex/shoreline-components package.

I've added some tags to help to understand the size of the change on each component, you can check below what each tag means:

• codemod: we can implement a codemod for the change
• documentation: the changes on the component API it's complex and it's better to reimplement the component from scratch by following the instructions on the documentation
• import-only: the component has the same API and we only need to change its import from admin-ui to shoreline.

Alert

tags: codemod;

• The action property doesn’t exist anymore. Now you must add the action by hand using the Button component
• the variant property values has changed from 'info' | 'positive' | 'warning' | 'critical' to 'informational' | 'success' | 'critical' | 'warning'

Before

<Alert
  variant="warning"  
  action={{
    children: 'See order',
    onClick: () => alert('Order #123'),
  }}
>
  <Text variant="body">Action as button</Text>
  <Button variant="tertiary" onClick={() => alert('Clicked')}>
    Action
  </Button>
</Alert>

After

<Alert variant="warning">
  <Text variant="body">Action as button</Text>
  <Button variant="tertiary" onClick={() => alert('Clicked')}>
    Action
  </Button>
</Alert>

Bleed

tags: codemod;

• the properties left and right are now start and end.

After

<Bleed left="" right="" bottom="" top="">
  ...
</Bleed>

After

<Bleed start="" end="" bottom="" top="">
  ...
</Bleed>

Button

tags: codemod

• the variant property values has changed from primary | secondary | tertiary | critical |criticalSecondary |criticalTertiary | neutralTertiary to 'primary' | 'secondary' | 'tertiary' | 'critical' | 'criticalTertiary'
• The icon and iconPosition doesn’t exist, now you must use IconButton component.

Before

<Button icon={<IconPlus />} iconPosition="start">
  Create item
</Button>

After

<IconButton>
  <IconPlus />
  Create item
</IconButton>

Center

tags: codemod; import-only;

There are no changes.

Checkbox

tags: documentation;

• helpText, errorText, and error are now implemented using the Field component. You can check the Field documentation for detailed info.
• The label property was replaced by the children.
• The state property no longer exists, you must use the checked and onChange combination in order to control the checkbox state. The indeterminate property was also added to represent this state.

Before

const state = useCheckboxState()

<Checkbox label="" errorText="" error state={state} helpText="" />

After

<Field error>
  <Checkbox onChange={} checked>Label</Checkbox>
  <FieldDescription />
  <FieldError />
</Field>

Collections

tags: documentation;

This component replaces the old DataView component.

There are several changes in the component API, we’d recommend you to check the documentation before doing the migration.

ContextualHelp

tags: new

EmptyState

tags: new

It renders a styled empty state area. This component can be used combined with the Collections or Filter component

Field

tags: new

This component helps to implement form fields and it’s used combined with form components such as: Checkbox, Input, Textarea, Radio, etc.

Before

<Input
  value={}
  onChange={}
  label=""
  errorText=""
  error
  helpText=""
/>

After

<Field error>
  <Input
    value={}
    onChange={}
    label=""
    errorText=""
    error
    helpText=""
  />
  <FieldDescription />
  <FieldError />
</Field>

Filter

tags: documentation;

There are several changes in the component API, we’d recommend you to check the documentation before doing the migration.

Before

const filterState = useFilterState()

<> 
  <FilterDisclosure state={filterState}>Status</FilterDisclosure>

  <FilterPopover state={filterState}>
    <FilterListbox>
      <FilterOptionRadio id="#1" label="Full" />
      <FilterOptionRadio id="#2" label="Empty" />
      <FilterOptionRadio id="#3" label="Half full" />
    </FilterListbox>
    <FilterFooter />
  </FilterPopover>
</>

After

const [status, setStatus] = useState<string>('Experimental')

<Filter label="Status" value={status} setValue={setStatus}>
  <FilterItem value="Stable">Stable</FilterItem>
  <FilterItem value="Experimental">Experimental</FilterItem>
  <FilterItem value="Deprecated">Deprecated</FilterItem>
</Filter>

Flex

tags: codemod; import-only;

There are no changes.

Grid

tags: codemod; import-only;

There are no changes.

Heading

tags: codemod; import-only;

• We’ve added the variant property which changes text style.

Input

tags: codemod

• The name has changed from TextInput to Input
• helpText, and errorText are now implemented using the Field component. You can check the Field documentation for detailed info.

Label

tags: codemod; import-only;

• We’ve added the optional property that indicates whether the form field is optional or not.

Link

tags: codemod;

• The name has changed from Anchor to Link

Menu

There are several changes in the component API, we’d recommend you to check the documentation before doing the migration.

Before

const state = useMenuState()

<MenuButton state={state} />
<Menu state={state}>
  <MenuItem label="Create" icon={<IconPlus />} />
  <MenuItem label="Edit" icon={<IconPencil />} />
  <MenuItem label="Download" icon={<IconArrowLineDown />} />
</Menu>

After

// default
<Menu label="Open">
  <MenuItem>New Tab</MenuItem>
  <MenuItem>New Item</MenuItem>
  <MenuSeparator />
  <MenuItem>Downloads</MenuItem>
</Menu>

// composition
<MenuProvider>
  <MenuTrigger asChild>
    <Button>Open</Button>
  </MenuTrigger>
  <MenuPopover>
    <MenuItem>New Tab</MenuItem>
    <MenuItem>New Item</MenuItem>
    <MenuSeparator />
    <MenuItem>Downloads</MenuItem>
  </MenuPopover>
</MenuProvider>

Modal

tags: documentation;

We split the Modal component into two components:

ConfirmationModal: allow merchants to confirm an action through an overlay window that opens on top of the current page. Modal: allow users to view content that demands attention through an overlay window that opens on top of the current page.

There are several changes in the component API, we’d recommend you to check the documentation before doing the migration.

Page

tags: documentation;

There are several changes in the component API, we’d recommend you to check the documentation before doing the migration.

Pagination

tags: codemod;

• The pagination doesn’t have the usePaginationState hook anymore and now the state values should be passed as props

Before

const state = usePaginationState({ pageSize: 5, total: 35 })

<Pagination state={state} />

After

const [page, setPage] = useState({ page: 1 })

<Pagination
  page={pagination.page}
  onPageChange={(page) => {
    setPage(page)
  }}
  total={35}
  size={5}
 />

Radio

tags: codemod;

• helpText, errorText, and error are now implemented using the Field component. You can check the Field documentation for detailed info.
• The label property was replaced by the children. Now to add a label to the Radio you must pass it as a children.
• The property direction has changed to a horizontal which is a boolean prop and by default the direction is vertical.

Before

const state = useRadioState({ defaultValue: 'disabled' })

<RadioGroup state={state} label="Accounts" direction="column">
  <Radio
     label="Accounts are disabled"
     value="disabled"
  />
  <Radio
    label="Accounts are optional"
    value="optional"
  />
</RadioGroup>

After

const [value, setValue] = useState<string>()
const state = useRadioState({
  value,
  setValue: setValue as any,
})

<RadioGroup state={state} label="Accounts" direction="column">
  <Radio value="disabled">Accounts are disabled</Radio>
  <Radio value="optional">Accounts are optional</Radio>
</RadioGroup>

Search

tags: documentation;

• The search can’t be disabled anymore.
• The useSearchState no longer exists and the state should be handled by the user.

Select

tags: codemod;

• label, helpText, errorText, and error are now implemented using the Field component. You can check the Field documentation for detailed info.

Before

<Select label="Accounts" helpText="" error errorText="">
  <option value="disabled">Accounts are disabled</option>
  <option value="optional">Accounts are optional</option>
</Select>

After

<Field error>
  <Label>Accounts</Label>
  <Select helpText="">
    <option value="disabled">Accounts are disabled</option>
    <option value="optional">Accounts are optional</option>
  </Select>
  <FieldDescription />
  <FieldError />
</Field>

Skeleton

tags: codemod; import-only;

There are no changes.

Slot

tags: new;

A layout component to help in the structural composition.

Spinner

tags: codemod; import-only;

There are no changes.

Stack

tags: codemod;

• The property direction has changed to a horizontal which is a boolean prop and by default the direction is vertical.

Before

<Stack direction="row">...</Stack>

After

<Stack horizontal>...</Stack>

Tab

tags: documentation;

There are several changes in the component API, we’d recommend you to check the documentation before doing the migration.

Before

const state = useTabState()

<>
  <TabList state={state}>
    <Tab>Tab 1</Tab>
    <Tab>Tab 2</Tab>
  </TabList>
  <TabPanel state={state} />
  <TabPanel state={state} />
</>

After

<TabProvider>
  <TabList>
    <Tab>Tab 1</Tab>
    <Tab>Tab 2</Tab>
  </TabList>
  <TabPanel />
  <TabPanel />
</TabProvider>

Table

tags: documentation;

There are several changes in the component API, we’d recommend you to check the documentation before doing the migration.

Tag

tags: codemod;

• The label property no longer exist and now you must pass the label as the Tag children.

Before

<Tag label="Short text" />

After

<Tag>Short text</Tag>

Text

• The tone property no longer exists, you must set the text color by applying css to it.
• The variant value has changed from 'pageTitle' | 'title1' | 'title2' | 'action1' | 'action2' | 'display' | 'body' | 'detail' to 'context' | 'body' | 'action' | 'emphasis' | 'caption1' | 'caption2' | 'display1' | 'display2' | 'display3' | 'display4'

TextArea

tags: codemod

• helpText, and errorText are now implemented using the Field component. You can check the Field documentation for detailed info.

Tooltip

tags: documentation;

• Now the Tooltip can be used as an uncontrolled component and it’s not necessary to define its state every time you use it.
• The text property was renamed to label.

Before

const [visible, setVisible] = useState(false)

<Tooltip text="Tooltip text">...</Tooltip>

After

// uncontrolled
<Tooltip label="Tooltip text">...</Tooltip>

// controlled
const [open, setOpen] = useState(false)

<Tooltip open={} setOpen={} label="Tooltip text">...</Tooltip>

// composition
<TooltipProvider>
  <TooltipTrigger asChild>
    <button>i</button>
  </TooltipTrigger>
  <TooltipPopover>
    <TooltipArrow />
    Tooltip text
  </TooltipPopover>
</TooltipProvider>

Toast

tags: documentation;

There are several changes in the component API, we’d recommend you to check the documentation before doing the migration.

VisuallyHidden

tags: codemod; import-only;

There are no changes.

New components

• ConfirmationModal
• Content
• ContextualHelp
• EmptyState
• IconButton
• Popover
• Slot
• Field

Primitives

• AccessibleIcon
• Clickable
• Combobox
• LinkBox
• Select (Custom select)
• Virtual

Components renamed

• Anchor -> Link
• DataView -> Collections

Components without replacements

• Avatar
• BulkActions
• Card
• Collapsible
• Columns
• Divider
• Dropdown
• Form
• Inline
• List
• NumberInput
• Paragraph
• Switch
• Toolbar

[beatrizmilhomem]

@lucasaarcoverde is this documentation updated? This content should be moved to the documentation website. There is already a page about Design Migration so it would make sense for this content to live in the documentation too.

Proposal: Migration is expandable and includes pages Design and Code.

[matheusps]

Can we add this to the documentation site? @lucasaarcoverde