Bezier React v2 Release & Migration Guide #2123
sungik-choi
announced in
Announcements
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
What's Changed?
In bezier-react v2, we have addressed issues within the style system and improved the usability of components! 🎉
Removal of styled-components
Component Improvements
Box
, is introduced for easily implementing layouts without separate style files.className
property now always take precedence, leveraging CSS Cascade layers.Elevated Minimum Browser Support Version
Separation of the Design Token Library
How to Migrate?
Getting Started
Refer to the bezier-react releases to install the latest version of bezier-react.
yarn add @channel.io/bezier-react # For monorepos yarn up @channel.io/bezier-react
🤖 Icons Migration can be partially automated through the bezier-codemod library. You can execute it with the following command:
AppProvider
BezierProvider
has been renamed toAppProvider
. Unlike before, only one instance should exist at the application's root. Moreover, as styling is now done through precompiled style sheets rather than at runtime, you must import the library's style sheet at the application's root.Importing the Style Sheet at the Root of Your App
You can import it using a bundler like webpack or directly link the resource in your HTML.
Changing
BezierProvider
toAppProvider
at the Root of Your AppGlobal Style
Wrapping with
@layer base
To maintain the same behavior as before, global styles must be wrapped with
@layer base
. Since bezier-react uses CSS cascade layers internally, not wrapping them would result in global styles taking precedence.The order of bezier-react CSS cascade layers is as follows:
Warning
If you were using bezier-react's
createGlobalStyle
, you should switch to styled-components' function with the same name. Note that styled-components v5 does not recognize the @layer keyword and removes it, so you must upgrade to v6 or above. If you wish to keep v5, avoid usingcreateGlobalStyle
and opt for static CSS instead.Nested Theme
Using
ThemeProvider
instead of NestedBezierProvider
The combination of
BezierProvider
+Foundation
to set a specific theme has been replaced with usingThemeProvider
or a specific ThemeProvider (LightThemeProvider
,DarkThemeProvider
).Warning
Note that all theme-related provider components, including
ThemeProvider
, operate by assigning thedata-bezier-theme
attribute to sub-elements at runtime. Therefore, sub-elements must spread props, as they internally use radix-ui'sSlot
(Reference).Removal of
--inverted
CSS VariablesThe support for CSS variables starting with
--inverted
and thefoundation.subTheme
has been removed. Now, each theme can only access tokens specific to it. If you need to use inverted colors, please wrap the relevant area withInvertedThemeProvider
.Warning
The content areas of the
Tooltip
andToast
components are now set to the InvertedTheme area by default.Migration Strategies for Specific Cases
In cases where the color should follow the light theme and the background-color should follow the dark theme, the new design system's proximity-based theming may be challenging to adapt directly. While not recommended, you can migrate by directly accessing the
useThemeName
andtokens
object. Designs should evolve to avoid mixing theme contexts in the long term.🤖 Removal of
styled
,css
, and related APIs (v2-import-from-bezier-to-styled-components
)The
styled
,css
, and related APIs from styled-components are no longer provided. Please import them directly from styled-components.🤖 Foundation to CSS Variable Migration (
v2-foundation-to-css-variable
)The
foundation
object is no longer provided. Please migrate to the corresponding CSS variables. If you were directly importingLightFoundation
or similar objects, switch to using thetokens
object or the return value ofuseTokens
.Removal of
useFoundation
The
useFoundation
hook is no longer available. For accessing theme-related values, please useuseTokens
oruseThemeName
hooks as suitable replacements.🤖 Removal of Interpolation (
v2-interpolation-to-css-variable
)Support for mixins and constants such as
Typography
,ZIndex
,InputWrapperStyle
,Rounding
, etc., has been phased out in favor of corresponding CSS variables. Please note, the Spacing object is no longer provided but might be reintroduced as a design token in future updates based on clear specifications.Warning
As an exception, we no longer provide the
Spacing
object; we will add it as a design token in the future when the specification is clarified.Mixins
We no longer provide mixins (interpolation of styled-components). For mixins not mentioned, please refer to the link and implement them in your application.
Removal of
smoothCorners
Not supported. Please replace it with the
SmoothCornersBox
component.Removal of
gap
Not supported. please implement the function below in your app to use it.
Removal of
touchableHover
Not supported. please implement the function below in your app to use it.
Components
Common: Deprecation of
interpolation
propertyWith the inability to use interpolation from styled-components, all components no longer support the
interpolation
and related properties (e.g.,wrapperInterpolation
). Please migrate tostyle
and related properties (e.g.,wrapperStyle
). For override styles using selectors, you can migrate toclassName
and related properties.Common: Support for
as
Property in Certain Components OnlyTo prevent excessive flexibility, the support for the
as
property has been limited to the following components:Box
Stack
Text
Button
ListItem
OutlineItem
LegacyStack
LegacyStackItem
LegacyTooltip
🤖 Change in
Text
Component Interface (v2-text-component-interface
)The type of
typo
has been changed to string literals for an improved development experience.🤖 Transition of
Stack
Related Components from Legacy to Stable (v2-remove-alpha-from-alpha-components
)🤖 Conversion of Enum Members to String Literals (
v2-enum-member-to-string-literal
)Enum members such as
***Size
,***Variant
have been converted to string literals to enhance autocomplete and improve the developer experience.Changes in
ListItem
Interface and SizeiconStyle
,iconClassName
,iconInterpolation
,contentStyle
,contentClassName
, andcontentInterpolation
are no longer supported. These were removed to reduce excessive flexibility within the interface.leftIcon
property is no longer supported. This change aligns with the consistency across other component interfaces. Please useleftContent
instead.name
property is no longer supported. Additionally, the second parameter (name) in theonClick
has been removed. If an identifier is needed, please combine functions externally to the component.hide
,nested
,optionKey
, anddisableIconActive
are no longer supported. These legacy properties have been removed. For hiding elements, please use conditional rendering.ListItemSize
have changed to unify the design. Please adjust accordingly:ListItemSize.S
->ListItemSize.XS
ListItemSize.M
->ListItemSize.S
ListItemSize.L
->ListItemSize.M
ListItemSize.XL
->ListItemSize.L
Changes in
NavItem
,NavGroup
InterfaceThe
leftIcon
property is no longer supported, for consistency across other component interfaces. Please useleftContent
instead.Changes in
TextField
InterfaceTextFieldVariant
has been removed. Please use string literals instead.inputStyle
andinputClassName
are no longer supported. Please usestyle
andclassName
instead.Changes in
TextArea
InterfaceThe properties
wrapperStyle
andwrapperClassName
are no longer supported.Changes in Name and Interface of
KeyValueListItem
Renamed to
KeyValueItem
to align with the design system naming convention. Similarly,KeyValueMultiLineListItem
has been changed toKeyValueMultiLineItem
.Changes in
SectionLabel
Interface and Internal ImplementationTo enhance design consistency and simplify component responsibilities, the internal implementation has been changed:
div
wrapper. Usestyle
andclassName
in place ofwrapperStyle
andwrapperClassName
.divider
property. Please use theDivider
component directly.iconColor
inleftContent
,rightContent
properties.onClick
handler is injected, the root element is improved to become abutton
to support keyboard focus behavior.Changes in
OutlineItem
Interface and Internal ImplementationOriginally designed for implementing a tree view, however, it was observed that no place in the desk used OutlineItem's inherent functionality for this purpose. Thus, unused properties have been removed to simplify the component's responsibilities:
paddingLeft
property is no longer supported. A default padding of 6px is now added, consistent with the design specifications.icon
andcontent
have been removed.leftIcon
property is no longer supported, for consistency across other component interfaces. Please useleftContent
instead.name
property is no longer supported, and the second parameter(name) inonClick
has also been removed. If an identifier is needed, please combine functions externally to the component.hide
,optionKey
, anddisableIconActive
are no longer supported as they were legacy properties. Use conditional rendering for hiding elements.onOpen
,onClickArrow
,selectedOutlineItemIndex
, andonChangeOption
properties.Removal of
ListMenuTitle
This component is no longer used in the design system. If there's a use case in your application, please switch to using
SectionLabel
.Changes in
Tag
Interface and Removal ofTagBadgeColorPreset
color
property ofTag
is no longer supported. Only predefined variants can be used through thevariant
property, to maintain consistency.TagBadgeColorPreset
has been removed.Removal of
TagBadgeSize
&TagBadgeVariant
Removed for consistency with other components. Please use
TagSize
,BadgeSize
, orTagVariant
,BadgeVariant
instead.Removal of Default
offset
inToast
This style was specific to certain applications within Channel, hence it has been removed. To achieve the same behavior as before, please add the following
offset
object as a default:Removal of
TooltipProvider
Removed for performance reasons.
Types
Removal of
InterpolationProps
No longer provided. Please use the return type of styled-components'
css
for similar purposes.Changes to
BezierComponentProps
The interface, which included properties like
as
andinterpolation
, has been updated to extendHTMLAttributes<T extends HTMLElement>
, streamlining it with standard HTML attribute extensions.as
type declaration, consider utilizingPolymorphicProps
.testId
property has been removed. If you were usingtestId
for queries in a testing-library environment, you should switch to using thedata-testid
attribute.Renaming
SemanticNames
This has been changed to
SemanticColor
to better reflect its purpose and usage.Renaming
FormComponentProps
These are now referred to as
FormFieldProps
, aligning with their role in form components more accurately.Hooks & Utilities
Removal of
useEventHandler
This hook is no longer provided. Please refer to the provided link for implementation guidance if needed in your application.
Removal of
useMergeRefs
This hook is no longer provided. Please refer to the link for implementation guidance if needed in your application.
Removal of
useId
This hook is no longer provided. Please refer to the link for implementation guidance if needed in your application.
Removal of
getRootElement
Instead of
getRootElement
, you are encouraged to use theuseRootElement
hook. This change accommodates the addition of features like new windows, where accessing the nearest context's window is necessary.Other Improvements
Text
component now supports thealign
property for text alignment.Stack
component has introduced a newjustify
option,between
, for evenly spacing children.Banner
component now correctly renders content, whether it is a string or a component.size
property has been added toFormControl
, which affectsSelect
andTextField
components, ensuring uniform height when labels are positioned on the left.Radio
component will now shrink to the size of the indicator if no label (children) is provided.Q&A
Do I need to migrate all styled-components in my application?
No, you do not need to migrate. The main objective is removing styled-components from bezier-react dependencies, which does not directly affect the styling system of your application.
How do I handle CSS for unused components?
This issue is challenging to address. Currently, only a single stylesheet is provided. In the future, we plan to explore solutions like PurgeCSS to remove unused CSS from applications.
How can I ensure type safety with the new version?
Since CSS variables do not benefit from TypeScript's typing, referencing a non-existent design token will not result in a compile-time error. For type safety, use layout components like
Box
, where interface properties are type-checked.Future developments, such as a stylelint plugin, may help detect errors at the linting stage.
Won't the lack of IDE autocomplete for CSS variables be inconvenient?
We plan to develop a VSCode extension to support autocomplete functionality for CSS variables, aiming to improve the development experience.
Beta Was this translation helpful? Give feedback.
All reactions