v0.132.0

Bug Fixes

• Inline: margin styles were being applied not only to direct children but for all nested children
• Combobox: empty state only appeared when 2 or more letters were entered, causing a confusing delay

Features

Menu

🚨 Breaking Changes 🚨

The way of using the Menu component is a little bit different. Below you can see what are the breaking changes in this version, but you should also check the documentation to look for new features.

• The Wrapper component named Menu was removed.
• The prop hideOnClick was removed. The menu is closed on item click.
• MenuList was renamed to Menu.
• The state needs to be passed to Menu and MenuButton.
• MenuButton has now a label prop to set its text.
• MenuButton has IconDotsThreeVertical as the default icon, but if you pass a custom label the icon changes to IconCaretDown/Up.
• MenuButton has the labelHidden prop to hide its own label. In this case the icon is always IconDotsThreeVertical.
• MenuItem has now a label property to set its text.
• MenuItem has now a boolean prop called critical to set it to critical tone.

Before

import {
  useMenuState,
  MenuList,
  MenuButton,
  MenuItem,
  MenuSeparator,
} from '@vtex/admin-ui'

function Example() {
  const state = useMenuState()

  return (
    <Menu state={state} hideOnClick>
      <MenuButton display="menu" />
      <MenuList aria-label="Menu">
        <MenuItem icon={<IconPlus />}>Create</MenuItem>
        <MenuItem icon={<IconPencil />}>Edit</MenuItem>
        <MenuItem icon={<IconArrowLineDown />}>Download</MenuItem>
        <MenuSeparator />
        <MenuItem icon={<IconTrash />} tone="critical">
          Delete
        </MenuItem>
      </MenuList>
    </Menu>
}

After

import {
  MenuButton,
  Menu,
  MenuItem,
  MenuDivider,
  useMenuState
} from '@vtex/admin-ui'

function Example() {
  const state = useMenuState()

  return (
   <>
     <MenuButton state={state} />
     <Menu state={state} aria-label="Menu">
       <MenuItem label="Create" icon={<IconPlus />} />
       <MenuItem label="Edit" icon={<IconPencil />} />
       <MenuItem label="Download" icon={<IconArrowLineDown />} />
       <MenuDivider />
       <MenuItem label="Delete" icon={<IconTrash />} critical />
     </Menu>
    </>
 )

DataGrid

🚨 Breaking Changes 🚨

Below you can see what are the breaking changes in this version, but you should also check the documentation to look for new features.

• The DataGrid and all its references was renamed to Table.
• Remove the density prop from table. Now, the minimum row height is 44px and it grows depending on the content of its cells.

New Features

• Create a text resolver to render a text and an optional description just below it. You can read more about it in the resolver section under the Code tab.

  Usage

  const state = useTableState({
      columns: [
        {
            id: 'name',
            header: 'Name',
            resolver: {
            type: 'text', // Resolver name
            columnType: 'name',
            mapText: (item) => item.name,
            mapDescription: (item) => item.description, // Optional text description
        },
        // Other table columns...
     ]
  })

NumberInput

🚨 Breaking Changes 🚨

The NumericStepper component does not exist anymore, it has been replaced by the NumberInput component. Below you can see what are the breaking changes in this version, but you should also check the documentation to look for new features.

Before

import { NumericStepper } from '@vtex/admin-ui'

function Example() {
  const [value, setValue] = React.useState(0)

  return (
    <NumericStepper
      value={value}
      helperText="Helper Text"
      label="numeric-stepper"
      onChange={(event) => setValue(event.value)}
    />
  )
}

After

import { NumberInput } from '@vtex/admin-ui'

function Example() {
  const [value, setValue] = useState('')

  return (
    <NumberInput
      value={value}
      label="Label"
      helpText="Help text"
      onChange={(newValue) => setValue(newValue)}
    />
  )
}

Tag

🚨 Breaking Changes 🚨

• The icon and handleDelete properties were removed.
• The size property now accepts normal and large, instead of small and regular.

You can use our codemod cli to update the tag's properties for you. See its README for more information on how to execute the codemod.

Before

import { Tag } from '@vtex/admin-ui'

function Example() {
  return (
    <Tag
      icon={<IconHeart />}
      label="Here goes the label!"
      size="small"
      handleDelete={() => window.alert('Tag deleted')}
    />
  )
}

After

import { Tag } from '@vtex/admin-ui'

function Example() {
  return <Tag label="Short text" size="normal" />
}

Alert

🚨 Breaking Changes 🚨

• The icon, fluid, visible, and sticky properties were removed.
• The fluid behavior was incorporated as default for it.
• Each variant has its own default icon now.
• The tone prop was renamed to variant.

You can use our codemod cli to update the alert's properties for you. See its README for more information on how to execute the codemod.

Before

import { Alert } from '@vtex/admin-ui'

function Example() {
  return (
    <Alert icon={<IconHeart />} fluid sticky visible>
      Hello world
    </Alert>
  )
}

After

import { Alert } from '@vtex/admin-ui'

function Example() {
  return <Alert visible>Hello world</Alert>
}

Select

🚨 Breaking Changes 🚨

• The way of handling errors is different now. Before we used a combination of tone and criticalText, and now we use error and errorText.
• helperText now is helpText
• The placeholder is internationalized and it always shows Select....
• tone and criticalText doesn't exist anymore.

Before

<Select
  label="Disabled"
  helperText="Helpful text"
  criticalText="Critical message"
  value={value}
  tone="critical"
  onChange={(e) => setValue(e.target.value)}
  disabled
>
  <option value="yesterday">Yesterday</option>
  <option value="today">Today</option>
</Select>

After

<Select
  label="Disabled"
  helpText="Helpful text"
  errorText="Critical message"
  error
  value={value}
  onChange={(e) => setValue(e.target.value)}
  disabled
>
  <option value="yesterday">Yesterday</option>
  <option value="today">Today</option>
</Select>

Page

🚨 Breaking Changes 🚨

• PageAction is now PageHeaderAction
• PageTitle is now PageHeaderTitle

🎉 New Features 🎉

• PageHeaderTop composite
• PageHeaderBottom composite
• PageHeaderButton composite that should be used in place of the Button component within the PageHeaderActions
• PageHeaderMenuButton composite that should be used in place of the MenuButton component within the PageHeaderActions
• PageHeaderTags wrapper that should be used within the PageHeaderTitle component
• PageHeaderTag composite that should be used within the PageHeaderTags component

Before

import {
  Page,
  PageHeader,
  PageTitle,
  PageActions,
  PageContent,
} from '@vtex/admin-ui'

function WithSearch() {
  const view = useDataViewState()
  const search = useSearchState()

  const searchedItems = searchLogic()
  const grid = gridState()

  return (
    <Page>
      <PageHeader onPopNavigation={() => alert('should go back')}>
        <PageTitle>Page Title</PageTitle>
        <PageActions>
          <Button variant="tertiary">Tertiary Action</Button>
          <Button variant="secondary">Secondary Action</Button>
          <Button>Primary Action</Button>
        </PageActions>
      </PageHeader>
      <PageContent>
        <DataView state={view}>
          <DataViewControls>
            <Search id="search" placeholder="Search" state={search} />
          </DataViewControls>
          <DataGrid state={grid} />
        </DataView>
      </PageContent>
    </Page>
  )
}

After

import {
  Page,
  PageHeader,
  PageHeaderTop,
  PageHeaderTitle,
  PageHeaderTags,
  PageHeaderTag,
  PageHeaderActions,
  PageHeaderButton,
  PageHeaderMenuButton,
  PageHeaderBottom,
  PageContent,
} from '@vtex/admin-ui'

function Example() {
  const view = useDataViewState()
  const search = useSearchState()
  const tabs = useTabState()
  const state = useMenuState()

  const searchedItems = searchLogic()
  const table = tableData()

  return (
    <Page>
      <PageHeader onPopNavigation={() => alert('should go back')}>
        <PageHeaderTop>
          <PageHeaderTitle>
            Product #123{' '}
            <PageHeaderTags>
              <PageHeaderTag label="Short text" />
            </PageHeaderTags>
          </PageHeaderTitle>
          <PageHeaderActions>
            <PageHeaderButton>Create</PageHeaderButton>
            <PageHeaderMenuButton state={state} />
            <Menu state={state} aria-label="actions">
              <MenuItem label="Create" icon={<IconPlus />} />
              <MenuItem label="Edit" icon={<IconPencil />} />
            </Menu>
          </PageHeaderActions>
        </PageHeaderTop>
        <PageHeaderBottom>
          <TabList state={tabs}>
            <Tab id="1">Label</Tab>
            <Tab id="2">Label</Tab>
            <Tab id="3">Label</Tab>
          </TabList>
        </PageHeaderBottom>
      </PageHeader>
      <PageContent>
        <DataView state={view}>
          <DataViewControls>
            <Search id="search" placeholder="Search" state={search} />
          </DataViewControls>
          <Table state={table} />
        </DataView>
      </PageContent>
    </Page>
  )
}

Replace Emotion with Stitches

🚨 Breaking Changes 🚨

The createSystem function doesn't receive the key and experimentalEmotionOptions properties anymore.

Before

const [SystemProvider, emotion] = createSystem({ key: 'app-key' })

After

const [SystemProvider] = createSystem()

Filters

⚠️ All filter components are still experimental. Check the guidelines for experimental components.

🎉 New components 🎉

• FilterSearch a filter with option searching. You can check the usage details on the documentation.
• FilterMultipleSearch a filter with option searching that allows selection of more than one item. You can check the usage details on the documentation.

Deprecate admin-ui-formik

The admin-ui-formik library is deprecated and soon will no longer be maintained by the admin-ui team. However, we’ve implemented a solution on top of React Hook Form that you can use to replace the approach using Formik. For detailed info, you can visit this link: Form | Admin UI

Motivation

• We received reports about the Formik lib having performance issues
• Evolving the Formik components was difficult because it uses a different approach from admin-ui to handle the states.
• The new solution is easier to maintain and evolve since it’s a hook-based library

Tooltip

🚨 Breaking Changes 🚨

Below you can see what are the breaking changes in this version, but you should also check the documentation to look for new features.

• The label props was renamed to text.

New Features

• The Tooltip component can be used standalone.
• Added bleedX and bleedY props to trespass the parent element padding.

before

import { Tooltip } from '@vtex/admin-ui'

function Example() {
  return (
    <Tooltip label="Tooltip Label" placement="right">
      <Button icon={<IconCopySimple />} aria-label="Example button" />
    </Tooltip>
  )
}

after

import { Tooltip } from '@vtex/admin-ui'

function Example() {
  return <Tooltip text="Tooltip text" />

  // Or

  return (
    <Tooltip text="Copy files">
      <Button icon={<IconCopySimple />} variant="tertiary" />
    </Tooltip>
  )
}

TextArea

🚨 Breaking Changes 🚨

• helperText prop is now helpText
• charLimit is now maxLength
• criticalText is now errorText
• tone has been removed and you can use the boolean error to indicate an error state

Before

import { TextArea } from '@vtex/admin-ui'

function Example() {
  return (
    <TextArea
      label="With Error, help and counter"
      tone={'critical'}
      helperText="help text"
      criticalText="Error text"
      charLimit={120}
    />
  )
}

After

import { TextArea } from '@vtex/admin-ui'

function Example() {
  return (
    <TextArea
      label="With Error, help and counter"
      errorText="Error text"
      helpText="help text"
      maxLength={120}
      error
    />
  )
}