Skip to content

Commit

Permalink
Document deprecating passing null as alpha in the JS/Dart APIs
Browse files Browse the repository at this point in the history
  • Loading branch information
nex3 committed Aug 1, 2023
1 parent d48037a commit 0aabec5
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 0 deletions.
4 changes: 4 additions & 0 deletions source/documentation/breaking-changes/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ time-sensitive, so they may be released with new minor version numbers instead.

These breaking changes are coming soon or have recently been released:

* [Passing `null` as an alpha channel to `new SassColor()` is changing
behavior](/documentation/breaking-changes/null-alpha) beginning in Dart
Sass 1.64.3.

* [Loading Sass as a default export in JS is no longer
allowed](/documentation/breaking-changes/default-export) beginning in Dart
Sass 1.63.0.
Expand Down
57 changes: 57 additions & 0 deletions source/documentation/breaking-changes/null-alpha.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
title: "Breaking Change: Null Alpha Channel"
introduction: |
Prior to Dart Sass 1.64.3, in the JS and Dart APIs, if `null` was passed to
the `SassColor` constructor it would be treated as 1. This is now deprecated.
Users should explicitly pass 1 or `undefined` instead.
---

Sass is working on adding support for the [CSS Color Module Level 4]. One of the
changes in this module is the idea of ["missing components"]: if a color
component like `alpha` is missing, it's mostly treated as 0, but if it's
interpolated with another color (such as in a gradient or an animation) it will
automatically take on the other color's value.

[CSS Color Module Level 4]: https://www.w3.org/TR/css-color-4/
["missing components"]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components

We need a way for users of the JS and Dart APIs to access and set missing
channels, and `null` is the most natural way to do that. In most cases, this
isn't an issue; callers who intend to create opaque colors usually just leave
out the `alpha` parameter anyway (or pass `undefined` in JS). But if callers are
explicitly passing `null`, that will eventually be treated as a transparent
color instead of an opaque one.

To preserve the current behavior, all you need to do is explicitly pass 1 if
`alpha` is unset. In JS:

```js
new sass.SassColor({
red: 102,
green: 51,
blue: 153,
alpha: alpha ?? 1,
});
```
And in Dart:
```dart
sass.SassColor.rgb(102, 51, 153, alpha ?? 1);
```
{% funFact %}
The TypeScript types for the Sass API already forbid passing `null` as
`alpha`; it's only allowed to be absent, `undefined`, or a `Number`. But prior
to Dart Sass 1.64.3, if you weren't using TypeScript and you _did_ pass `null`
it would still be treated as an opaque color.
{% endfunFact %}
## Transition Period
{% compatibility 'dart: "1.64.3"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Between Dart Sass 1.64.3 and the upcoming release of support for CSS Colors
Level 4, Dart Sass will continue to interpret a `null` `alpha` value as an opaque
color. However, it will emit a deprecation warning to encourage authors to
explicitly pass `alpha` 1 instead.

0 comments on commit 0aabec5

Please sign in to comment.