Consolidate Breaking Changes in Tonic UI v3

[cheton]

Breaking Changes in Tonic UI v3

This issue will address the breaking changes introduced in Tonic UI v3.

🚧 (WIP) Use slots and slotProps to replace Component and ComponentProps

Inner element overrides

https://mui.com/material-ui/migration/migrating-from-deprecated-apis/#inner-element-overrides for details

The slots and slotProps APIs are in the process of being standardized. The analogous APIs—components, componentsProps, <SlotName>Component, and <SlotName>Props—are going to be deprecated and eventually removed. This improves the developer experience through consistency, predictability, and reduced cognitive load.

Affected components

The following components are affected by this change:

Name	Components	Deprecated Props
accordion	AccordionContent	TransitionComponent TransitionProps
date-pickers	DatePickerContent	PopperComponent PopperProps TransitionComponent TransitionProps
drawer	DrawerContent	TransitionComponent TransitionProps
drawer	DrawerOverlay	TransitionComponent TransitionProps
menu	MenuContent	PopperComponent PopperProps TransitionComponent TransitionProps
menu	SubmenuContent	PopperComponent PopperProps TransitionComponent TransitionProps
modal	ModalContent	TransitionComponent TransitionProps
modal	ModalOverlay	TransitionComponent TransitionProps
popover	PopoverContent	PopperComponent PopperProps PopoverArrowComponent PopoverArrowProps TransitionComponent TransitionProps
toast	ToastManager	TransitionComponent TransitionProps
toast	ToastTransitionController	TransitionComponent TransitionProps
tooltip	Tooltip	PopperComponent PopperProps TooltipArrowComponent TooltipArrowProps TransitionComponent TransitionProps
tooltip	TooltipContent	PopperComponent PopperProps TooltipArrowComponent TooltipArrowProps TransitionComponent TransitionProps
tree	TreeItem	TransitionComponent TransitionProps

Transition component and props update

TransitionComponent

The AccordionContent's TransitionComponent was deprecated in favor of slots.transition:

 <AccordionContent
-  TransitionComponent={CustomTransition}
+  slots={{ transition: CustomTransition }}
 />

TransitionProps

The AccordionContent's TransitionProps was deprecated in favor of slotProps.transition:

 <AccordionContent
-  TransitionProps={{ unmountOnExit: true }}
+  slotProps={{ transition: { unmountOnExit: true } }}
 />

Passing props to close buttons

To facilitate UI automation testing, you can use slotProps to pass custom properties to underlying components.

Alert

<Alert
  variant="solid"
  severity="success"
  isClosable
  onClose={onClose}
  slotProps={{
    closeButton: {
      'data-test': 'alert-close-button',
    },
  }}
>
  <Text>This is a success alert.</Text>
</Alert>

Drawer

<Drawer
  isOpen={isOpen}
  isClosable
  onClose={onClose}
  slotProps={{
    closeButton: {
      'data-test': 'drawer-close-button',
    },
  }}
>
  <DrawerOverlay />
  <DrawerContent>
    <DrawerHeader />
    <DrawerBody />
    <DrawerFooter />
  </DrawerContent>
</Drawer>

Modal

<Modal
  isOpen={isOpen}
  isClosable
  onClose={onClose}
  slotProps={{
    closeButton: {
      'data-test': 'modal-close-button',
    },
  }}
>
  <ModalOverlay />
  <ModalContent>
    <ModalHeader />
    <ModalBody />
    <ModalFooter />
  </ModalContent>
</Modal>

Tag

<Tag
  variant="solid"
  isClosable
  onClose={onClose}
  slotProps={{
    closeButton: {
      'data-test': 'tag-close-button',
    },
  }}
>
  <Text>This is a tag</Text>
</Tag>

Toast

<Toast
  appearance="success"
  isClosable
  onClose={onClose}
  slotProps={{
    closeButton: {
      'data-test': 'toast-close-button',
    },
  }}
>
  <Text>This is a success toast.</Text>
</Toast>

Updates for @tonic-ui/react

CSS variable configuration

• The theme.config option for CSS variables is deprecated. Use the cssVariables configuration instead.

  Deprecated:

  <TonicProvider
    theme={{
      config: {
        useCSSVariables: true,
        prefix: 'tonic',
      },
    }}
  />

  Updated:

  <TonicProvider
    theme={createTheme({
      cssVariables: true,
    })}
  />

  or

  <TonicProvider
    theme={createTheme({
      cssVariables: {
        prefix: 'tonic',
        rootSelector: ':root',
      },
    })}
  />

Calendar

• The Calendar component has been deprecated and will be removed in a future release. Use DateCalendar instead.
• The date and defaultDate props have been renamed to value and defaultValue, respectively.
• 🚧 [TODO] The firstDayOfWeek prop has been renamed to weekStartsOn.

DatePicker

• closeOnSelect: The default value has been updated from false to true, so the date picker will now automatically close when a date is selected.

Drawer

• [BREAKING CHANGES] closeOnOutsideClick has been renamed to closeOnInteractOutside (feat: enable granular control over outside interactions for drawers and modals #1033). While closeOnOutsideClick will remain available in v3, a deprecation warning will be shown.

LinearProgress

• The size prop has been removed.

Menu

• Removed the autoSelect prop as it is no longer used in the component.
• 🚧 [TODO] Replace closeOnBlur with closeOnInteractOutside

Modal

• closeOnOutsideClick has been renamed to closeOnInteractOutside (feat: enable granular control over outside interactions for drawers and modals #1033). While closeOnOutsideClick will remain available in v3, a deprecation warning will be shown.

Popper

• The anchorEl prop has been deprecated and will be removed in a future release. Use referenceRef instead.
• 🚧 [TODO] Renamed ref to popperRef for the popper DOM element.
• 🚧 [TODO] Renamed popperRef to ref` to receive the Popper instance.
• 🚧 [TODO] Replace closeOnBlur with closeOnInteractOutside

Spinner

• The lineColor, lineWidth, trackColor, and trackWidth props have been removed. For customization, use the CircularProgress component instead.

Updates for @tonic-ui/react-hooks

• useLatest is deprecated annd will be removed in a future release. Use useLatestRef instead.
• useOutsideClick is deprecated and will be removed in a future release. Use useClickOutside instead.

Updates for @tonic-ui/styled-system

• The properties _focusHover and _focusActive are deprecated and will be removed in the next major release. Instead, use _focus with nested selectors (PR #972):

  _focus={{
    '&:hover': {
      // Styles for `&:focus:hover`
    },
    '&:active': {
      // Styles for `&:focus:active`
    },
  }}

Updates for @tonic-ui/theme

• The createTheme function has been removed from the named exports.

  // Unit-specific themes
  export const rem = _rem(foundation);
  export const px = _px(foundation);
  
  // Export foundation directly
  export { foundation };