polished.js v3 is out!

Introducing polished.js v3!

We're super stoked to announce that polished.js v3 is officially out! It is available via your package manager of choice:

npm install polished
yarn add polished

Release Highlights

New Modules

• New Module: linearGradient: We've introduced a new module to handle generating linear gradients. linearGradient accepts an array of color stops, and optional directions and fallback to generate a linear gradient with a single color background fallback.
• New Module: math: We've introduced a new module to handle doing calculations on CSS values. math accepts a formula as a string and currently supports addition, subtraction, multiplication, division, square root, powers, factorial, min, max, and modification of order of operations parentheses. This can also be extended to incorporate other mathematical functions.
• New Module: hslToColorString: Converts a HslColor or HslaColor object to a color string. (Thanks @sandiiarov)
• New Module: rgbToColorString: Converts a RgbColor or RgbaColor object to a color string. (Thanks @sandiiarov)

Improvements

• New Error System: We now have the base for our long promised error system (Thanks @Andarist). All current errors will now show up in development, but will be stripped out and linked to our error.md in production. This reduces the overall bundle size and will set us up for our much more thorough error system coming in v4.
• Color Module Improvement: All color modules now safely handle the transparent keyword instead of erroring out. How each module handles this is slightly different, but you wll always get a valid color or transparent back when passing transparent to a color module.
• Color Module Improvement: Color modules that were using toColorString now properly use hslToColorString and rgbToColorString where appropriate. This speeds up color modules that were previously leveraging toColorString to convert colors between formats. (Thanks @sandiiarov)
• modularScale Improvement: modularScale now also accepts rem values for its base, where previously it only worked with em.
• readableColor Improvement: readableColor now offers the option to set the color(s) it returns for light or dark colors. Otherwise, it will work the way it always has, either returning white or black based on the passed colors luminosity.
• stripUnit Improvement: stripUnit now offers the option to return the value and unit as an array, replacing the functionality of getValueAndUnit. Without this option, it will continue to return just the stripped value.

Future Breaking Changes

• Marked For Deprecation: getValueAndUnit: getValueAndUnit has been marked for deprecation and will be removed in v4. This in someways duplicated functionality available in stripUnit. Instead of having two similar modules,stripUnit has been improved to optionally return the stripped unit as part of an array.

Breaking Changes

• Deprecation: selection: As indicated in the v2 release notes, selection has been deprecated. All css-in-js libraries handle this selector without additional prefixing from polished.
• Deprecation: placeholder: As indicated in the v2 release notes, placeholder has been deprecated. All css-in-js libraries handle this selector without additional prefixing from polished.

Coming In v4

As usual, we will be taking a bit of a break from major work for a couple months, but we are already planning out v4. This release will largely focus on library-wide impact, and likely won't include any new functionality. Here is the current state of the roadmap:

• Improved errors - We will be doing a complete re-write of our errors to drastically improve the developer experience.
• New Docs - polished.js has grown into a pretty robust library with a wide array of uses cases. There are a lot of things it can do that people are not aware of. Our aim with the new docs site is to provide a lot more insight on how to leverage polished.js regardless of your CSS-In-JS lirbary.
• Truly Support babel-plugin-polished - This plugin has been around since the early days of polished.js, but we've never taken official ownership of it. We will be pulling it forward in v4, updating it, and incorporating it into our testing and docs.
• Scoped Packages - Starting in v4, we are going to start offering sub-sections of polished.js as scoped packages. Plenty of users only use certain portions, and we want to provide them a smaller way to get the portions they use.
• Performance Audit - One thing we need to spend more time on is the performance of polished.js. We plan on performance testing each module in isolation and identifying areas for improvement in v4.
• Size Audit- Bundle size has always been tricky with polished.js. Due to the nature of the library, we have really focused on the total size, and instead of supported tree-shaking and individual imports to keep bundle-size impact down. That being said, we will be doing an module-by-module audit to see where we can bring file size down.
• Deprecate getValueAndUnit - v4 will see this module fully deprecated.