clones/sass
1
0
Fork 0
mirror of https://github.com/sass/sass.git synced 2024-09-21 10:37:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3930 from sass/feature.color-4

Browse Source 
Merge feature.color-4 into main
This commit is contained in:
Natalie Weizenbaum 2024-09-13 21:44:55 +00:00 committed by GitHub
commit 0150d3861d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
17 changed files with 2402 additions and 934 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
EMBEDDED_PROTOCOL_CHANGELOG.md
View File

@ -1,3 +1,9 @@
## 3.0.0
* Add `Color` SassScript value.
* Remove `RgbColor`, `HslColor` and `HwbColor` SassScript values.
## 2.7.1
* Allow deprecation versions to be value of `fatal_deprecation` field.
@ -53,7 +59,7 @@
* The `CompileRequest.id`, `CompileResponse.id`, `LogEvent.compilation_id`,
`CanonicalizeRequest.compilation_id`, `ImportRequest.compilation_id`,
`FileImportRequest.compilation_id`, and `FunctionCallRequest.compilation_id`
fields have been removed.
fields have been removed.
* The following fields are now explicitly declared as proto3 `optional` fields:
`ImportSuccess.source_map_url`, `LogEvent.span`, `SourceSpan.end`. These

10
accepted/color-4-new-spaces-js.changes.md
View File

@ -1,3 +1,13 @@
## Draft 1.8
* Change `SassColor.toGamut()` to take named parameters instead of positional.
* Add a mandatory `method` parameter to `SassColor.toGamut()`.
## Draft 1.7
* Don't throw errors for out-of-gamut lightness values.
## Draft 1.6
* Simplify the type definition for `interpolate`, and make `options` argument

28
accepted/color-4-new-spaces-js.d.ts.md
View File

@ -1,4 +1,4 @@
# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.6
# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.8
*([Issue](https://github.com/sass/sass/issues/2831),
[Changelog](color-4-new-spaces-js.changes.md))*
@ -116,6 +116,8 @@ export type HueInterpolationMethod =
| 'increasing'
| 'longer'
| 'shorter';
export type GamutMapMethod = 'clip' | 'local-minde';
```
### New Color Functions
@ -171,13 +173,16 @@ isInGamut(space?: KnownColorSpace): boolean;
#### `toGamut`
Returns the result of [`color.to-gamut(internal, space)`].
Returns the result of [`color.to-gamut(internal, space, method)`].
```ts
toGamut(space?: KnownColorSpace): SassColor;
toGamut(options: {
space?: KnownColorSpace;
method: 'clip' | 'local-minde';
}): SassColor;
```
[`color.to-gamut(internal, space)`]: ./color-4-new-spaces.md#colorto-gamut-1
[`color.to-gamut(internal, space, method)`]: ./color-4-new-spaces.md#colorto-gamut-1
#### `channelsOrNull`
@ -394,9 +399,6 @@ as the result of changing some of [`internal`]'s components.
* If `options.alpha` is set, and isn't either null or a number between 0 and 1
(inclusive and fuzzy), throw an error.
* If `options.lightness` is set, and isn't either null or a number between 0 and
the maximum channel value for the space (inclusive and fuzzy), throw an error.
* Let `color` be the result of [`this.toSpace(space)`].
* Let `changedValue` be a function that takes a string argument for `channel`
@ -624,8 +626,8 @@ Create a new SassColor in a color space with Lab channels—`lab` and `oklab`.
* If `options.space` equals `lab`, let `maximum` be `100`. Otherwise, let
`maximum` be `1`.
* Let `lightness` be the result of [parsing a clamped channel value] with
`value` of `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
* Let `lightness` be the result of [parsing a channel value] with `value` of
`options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
* Let `a` be the result of [parsing a channel value] with value `options.a`.
@ -663,8 +665,8 @@ Create a new SassColor in a color space with LCH channels—`lch` and `oklch`.
* If `options.space` equals `lch`, let `maximum` be `100`. Otherwise, let
`maximum` be `1`.
* Let `lightness` be the result of [parsing a clamped channel value] with
`value` of `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
* Let `lightness` be the result of [parsing a channel value] with `value` of
`options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
* Let `c` be the result of [parsing a channel value] with value `options.c`.
@ -777,8 +779,8 @@ Create a new SassColor in the `hsl` color space.
* Let `saturation` be the result of [parsing a channel value] with value
`options.saturation`.
* Let `lightness` be the result of [parsing a clamped channel value] with
`value` of `options.lightness`, `minimum` of `0`, and `maximum` of `100`.
* Let `lightness` be the result of [parsing a channel value] with `value` of
`options.lightness`, `minimum` of `0`, and `maximum` of `100`.
* If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
the result of [parsing a clamped channel value] with `value` of

70
accepted/color-4-new-spaces.changes.md
View File

@ -1,3 +1,73 @@
## Draft 1.20
* Many small wording and consistency changes.
* Remove outdated references to the possibility of unknown color spaces.
* Remove an outdated reference to the `specified` hue interpolation method.
* Make `color.complement()` and `color.invert()` produce errors when color
channels are missing, for forwards-compatibility.
* When passing a legacy color to a color manipulation function that operates in
another space, ensure that channels aren't marked as `none` in the conversion
back to the legacy color.
* Properly include alpha as the *first* channel in `color.ie-hex-str()` rather
than the last.
## Draft 1.19
* Be stricter about which colors are allowed with slash-separated strings at the
end.
## Draft 1.18
* Treat missing channels as distinct from 0 for `==`-equality for colors.
* Convert missing channels to 0 before color conversion for `color.same()`.
* Explicitly support `none` values for `alpha` in Parsing Color Components and
`color.change()`,
* Clarify how to handle existing missing components in `color.adjust()` and
`color.scale()`.
* Remove language misleadingly indicating that the scaling a number algorithm
was guaranteed to return an in-gamut number.
* Ensure that `color.invert()` and `color.grayscale()` always return colors in
the original color's space.
* Make `color.invert()` throw an error for an invalid `$weight`.
* Include CSS-compatibility behavior for `color.invert()` and
`color.grayscale()`.
* Explicitly mandate `local-minde` gamut-mapping for `ie-hex-str()`.
## Draft 1.17
* Treat colors with missing channels as the same as 0 for `color.same()`.
## Draft 1.16
* Explicitly require case-sensitivity for channel names in Sass functions.
## Draft 1.15
* Add a mandatory `$method` parameter to `color.to-gamut()` for
forwards-compatibility with better gamut-mapping algorithms.
* Add `clip` as a gamut-mapping algorithm.
## Draft 1.14
* Update the definition of powerless for HWB to match [the latest CSS
spec][color-4-changes-20221101].
[color-4-changes-20221101]: https://drafts.csswg.org/css-color-4/#changes-from-20221101
## Draft 1.13
* Remove definitions of powerless channels that are no longer present in CSS

1311
accepted/color-4-new-spaces.md
View File

File diff suppressed because it is too large Load Diff

16
js-api-doc/deprecations.d.ts vendored
View File

@ -6,7 +6,7 @@
*/
export interface Deprecations {
// START AUTOGENERATED LIST
// Checksum: bf841a728263bf7efc2a85a091330a1f8074e067
// Checksum: 5470e7252641d3eaa7093b072b52e423c3b77375
/**
* Deprecation for passing a string directly to meta.call().
@ -127,6 +127,20 @@ export interface Deprecations {
*/
'feature-exists': Deprecation<'feature-exists'>;
/**
* Deprecation for certain uses of built-in sass:color functions.
*
* This deprecation became active in Dart Sass 1.79.0.
*/
'color-4-api': Deprecation<'color-4-api'>;
/**
* Deprecation for using global color functions instead of sass:color.
*
* This deprecation became active in Dart Sass 1.79.0.
*/
'color-functions': Deprecation<'color-functions'>;
/**
* Deprecation for @import rules.
*

18
js-api-doc/index.d.ts vendored
View File

@ -45,7 +45,25 @@ export {
CalculationOperation,
CalculationOperator,
CalculationValue,
ChannelName,
ChannelNameHsl,
ChannelNameHwb,
ChannelNameLch,
ChannelNameLab,
ChannelNameRgb,
ChannelNameXyz,
ColorSpaceHsl,
ColorSpaceHwb,
ColorSpaceLch,
ColorSpaceLab,
ColorSpaceRgb,
ColorSpaceXyz,
GamutMapMethod,
HueInterpolationMethod,
KnownColorSpace,
ListSeparator,
PolarColorSpace,
RectangularColorSpace,
SassArgumentList,
SassBoolean,
SassCalculation,

572
js-api-doc/value/color.d.ts vendored
View File

@ -1,5 +1,103 @@
import {List} from 'immutable';
import {Value} from './index';
/** The HSL color space name. */
export type ColorSpaceHsl = 'hsl';
/** The HSL color space channel names. */
export type ChannelNameHsl = 'hue' | 'saturation' | 'lightness' | 'alpha';
/** The HWB color space name. */
export type ColorSpaceHwb = 'hwb';
/** The HWB color space channel names. */
export type ChannelNameHwb = 'hue' | 'whiteness' | 'blackness' | 'alpha';
/** The Lab / Oklab color space names. */
export type ColorSpaceLab = 'lab' | 'oklab';
/** The Lab / Oklab color space channel names. */
export type ChannelNameLab = 'lightness' | 'a' | 'b' | 'alpha';
/** The LCH / Oklch color space names. */
export type ColorSpaceLch = 'lch' | 'oklch';
/** The LCH / Oklch color space channel names. */
export type ChannelNameLch = 'lightness' | 'chroma' | 'hue' | 'alpha';
/** Names of color spaces with RGB channels. */
export type ColorSpaceRgb =
| 'a98-rgb'
| 'display-p3'
| 'prophoto-rgb'
| 'rec2020'
| 'rgb'
| 'srgb'
| 'srgb-linear';
/** RGB channel names. */
export type ChannelNameRgb = 'red' | 'green' | 'blue' | 'alpha';
/** Names of color spaces with XYZ channels. */
export type ColorSpaceXyz = 'xyz' | 'xyz-d50' | 'xyz-d65';
/** XYZ channel names. */
export type ChannelNameXyz = 'x' | 'y' | 'z' | 'alpha';
/** All supported color space channel names. */
export type ChannelName =
| ChannelNameHsl
| ChannelNameHwb
| ChannelNameLab
| ChannelNameLch
| ChannelNameRgb
| ChannelNameXyz;
/** All supported color space names. */
export type KnownColorSpace =
| ColorSpaceHsl
| ColorSpaceHwb
| ColorSpaceLab
| ColorSpaceLch
| ColorSpaceRgb
| ColorSpaceXyz;
/** Polar color space names (HSL, HWB, LCH, and Oklch spaces). */
export type PolarColorSpace = ColorSpaceHsl | ColorSpaceHwb | ColorSpaceLch;
/** Rectangular color space names (Lab, Oklab, RGB, and XYZ spaces). */
export type RectangularColorSpace = Exclude<KnownColorSpace, PolarColorSpace>;
/**
* Methods by which two hues are adjusted when interpolating between polar
* colors.
*/
export type HueInterpolationMethod =
| 'decreasing'
| 'increasing'
| 'longer'
| 'shorter';
/**
* Methods by which colors in bounded spaces can be mapped to within their
* gamut.
*
* * `local-minde`: The algorithm specified in [the original Color Level 4
* candidate recommendation]. This maps in the Oklch color space, using the
* [deltaEOK] color difference formula and the [local-MINDE] improvement.
*
* * `clip`: Clamp each color channel that's outside the gamut to the minimum or
* maximum value for that channel. This algorithm will produce poor visual
* results, but it may be useful to match the behavior of other situations in
* which a color can be clipped.
*
* [the original Color Level 4 candidate recommendation]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#css-gamut-mapping
* [deltaEOK]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#color-difference-OK
* [local-MINDE]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#GM-chroma-local-MINDE
*/
export type GamutMapMethod = 'clip' | 'local-minde';
/**
* Sass's [color type](https://sass-lang.com/documentation/values/colors).
*
@ -10,119 +108,459 @@ import {Value} from './index';
*/
export class SassColor extends Value {
/**
* Creates an RGB color.
* Creates an [RGB color].
*
* **Only** `undefined` should be passed to indicate a missing `alpha`. If
* `null` is passed instead, it will be treated as a [missing component] in
* future versions of Dart Sass. See [breaking changes] for details.
* If `space` is missing, **only** `undefined` should be used to indicate that
* `alpha` isn't passed. If `null` is used instead, it will be treated as a
* [missing component]. See [breaking changes] for details.
*
* If `space` is defined and `null` is passed for any component, it will be
* treated as a [missing component].
*
* [RGB color]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb
* [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
* [breaking changes]: /documentation/breaking-changes/null-alpha
*
* @throws `Error` if `red`, `green`, and `blue` aren't between `0` and
* `255`, or if `alpha` isn't between `0` and `1`.
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
constructor(options: {
red: number;
green: number;
blue: number;
alpha?: number;
red: number | null;
green: number | null;
blue: number | null;
alpha?: number | null;
space?: 'rgb';
});
/**
* Creates an HSL color.
* Creates an [HSL color].
*
* **Only** `undefined` should be passed to indicate a missing `alpha`. If
* `null` is passed instead, it will be treated as a [missing component] in
* future versions of Dart Sass. See [breaking changes] for details.
* If `space` is missing, **only** `undefined` should be used to indicate that
* `alpha` isn't passed. If `null` is used instead, it will be treated as a
* [missing component]. See [breaking changes] for details.
*
* If `space` is defined and `null` is passed for any component, it will be
* treated as a [missing component].
*
* [HSL color]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl
* [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
* [breaking changes]: /documentation/breaking-changes/null-alpha
*
* @throws `Error` if `saturation` or `lightness` aren't between `0` and
* `100`, or if `alpha` isn't between `0` and `1`.
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
constructor(options: {
hue: number;
saturation: number;
lightness: number;
alpha?: number;
hue: number | null;
saturation: number | null;
lightness: number | null;
alpha?: number | null;
space?: ColorSpaceHsl;
});
/**
* Creates an HWB color.
* Creates an [HWB color].
*
* **Only** `undefined` should be passed to indicate a missing `alpha`. If
* `null` is passed instead, it will be treated as a [missing component] in
* future versions of Dart Sass. See [breaking changes] for details.
* If `space` is missing, **only** `undefined` should be used to indicate that
* `alpha` isn't passed. If `null` is used instead, it will be treated as a
* [missing component]. See [breaking changes] for details.
*
* If `space` is defined and `null` is passed for any component, it will be
* treated as a [missing component].
*
* [HWB color]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hwb
* [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
* [breaking changes]: /documentation/breaking-changes/null-alpha
*
* @throws `Error` if `whiteness` or `blackness` aren't between `0` and `100`,
* or if `alpha` isn't between `0` and `1`.
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
constructor(options: {
hue: number;
whiteness: number;
blackness: number;
alpha?: number;
hue: number | null;
whiteness: number | null;
blackness: number | null;
alpha?: number | null;
space?: ColorSpaceHwb;
});
/** This color's red channel, between `0` and `255`. */
get red(): number;
/**
* Creates a [Lab] or [Oklab] color.
*
* If `null` is passed for any component, it will be treated as a [missing
* component].
*
* [Lab]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lab
* [Oklab]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklab
* [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
constructor(options: {
lightness: number | null;
a: number | null;
b: number | null;
alpha?: number | null;
space: ColorSpaceLab;
});
/** This color's green channel, between `0` and `255`. */
get green(): number;
/**
* Creates an [LCH] or [Oklch] color.
*
* If `null` is passed for any component, it will be treated as a [missing
* component].
*
* [LCH]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lch
* [Oklch]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch
* [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
constructor(options: {
lightness: number | null;
chroma: number | null;
hue: number | null;
alpha?: number | null;
space: ColorSpaceLch;
});
/** This color's blue channel, between `0` and `255`. */
get blue(): number;
/**
* Creates a color in a predefined [RGB color space].
*
* If `null` is passed for any component, it will be treated as a [missing
* component].
*
* [RGB color space]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color#using_predefined_colorspaces_with_color
* [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
constructor(options: {
red: number | null;
green: number | null;
blue: number | null;
alpha?: number | null;
space: Exclude<ColorSpaceRgb, 'rgb'>;
});
/** This color's hue, between `0` and `360`. */
get hue(): number;
/**
* Creates a color in a predefined [XYZ color space].
*
* If `null` is passed for any component, it will be treated as a [missing
* component].
*
* [XYZ color space]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color#using_the_xyz_colorspace_with_color
* [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
constructor(options: {
x: number | null;
y: number | null;
z: number | null;
alpha?: number | null;
space: ColorSpaceXyz;
});
/** This color's saturation, between `0` and `100`. */
get saturation(): number;
/** The name of this color's space. */
get space(): KnownColorSpace;
/** This color's lightness, between `0` and `100`. */
get lightness(): number;
/**
* Returns a new color that's the result of converting this color to the
* specified `space`.
*/
toSpace(space: KnownColorSpace): SassColor;
/** This color's whiteness, between `0` and `100`. */
get whiteness(): number;
/**
* A boolean indicating whether this color is in a legacy color space (`rgb`,
* `hsl`, or `hwb`).
*/
get isLegacy(): boolean;
/** This color's blackness, between `0` and `100`. */
get blackness(): number;
/**
* Returns a boolean indicating whether this color is in-gamut (as opposed to
* having one or more of its channels out of bounds) for the specified
* `space`, or its current color space if `space` is not specified.
*/
isInGamut(space?: KnownColorSpace): boolean;
/**
* Returns a copy of this color, modified so it is in-gamut for the specified
* `space`—or the current color space if `space` is not specified—using
* `method` to map out-of-gamut colors into the desired gamut.
*/
toGamut(options: {
space?: KnownColorSpace;
method: GamutMapMethod;
}): SassColor;
/**
* A list of this color's channel values (excluding alpha), with [missing
* channels] converted to `null`.
*
* [missing channels]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*/
get channelsOrNull(): List<number | null>;
/**
* A list of this color's channel values (excluding alpha), with [missing
* channels] converted to `0`.
*
* [missing channels]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*/
get channels(): List<number>;
/**
* Returns the value of a single specified `channel` of this color, with
* [missing channels] converted to `0`.
*
* [missing channels]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*
* @throws `Error` if `channel` is not `alpha` or a channel in this color's
* space.
*/
channel(channel: ChannelName): number;
/**
* Returns the value of a single specified `channel` of this color after
* converting this color to the specified `space`, with [missing channels]
* converted to `0`.
*
* [missing channels]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*
* @throws `Error` if `channel` is not `alpha` or a channel in `space`.
*/
channel(channel: ChannelNameHsl, options: {space: ColorSpaceHsl}): number;
channel(channel: ChannelNameHwb, options: {space: ColorSpaceHwb}): number;
channel(channel: ChannelNameLab, options: {space: ColorSpaceLab}): number;
channel(channel: ChannelNameLch, options: {space: ColorSpaceLch}): number;
channel(channel: ChannelNameRgb, options: {space: ColorSpaceRgb}): number;
channel(channel: ChannelNameXyz, options: {space: ColorSpaceXyz}): number;
/** This color's alpha channel, between `0` and `1`. */
get alpha(): number;
/**
* Changes one or more of this color's RGB channels and returns the result.
* Returns a boolean indicating whether a given channel value is a [missing
* channel].
*
* [missing channel]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
*/
change(options: {
red?: number;
green?: number;
blue?: number;
alpha?: number;
}): SassColor;
isChannelMissing(channel: ChannelName): boolean;
/**
* Changes one or more of this color's HSL channels and returns the result.
* Returns a boolean indicating whether a given `channel` is [powerless] in
* this color. This is a special state that's defined for individual color
* spaces, which indicates that a channel's value won't affect how a color is
* displayed.
*
* [powerless]: https://www.w3.org/TR/css-color-4/#powerless
*/
change(options: {
hue?: number;
saturation?: number;
lightness?: number;
alpha?: number;
}): SassColor;
isChannelPowerless(channel: ChannelName): boolean;
isChannelPowerless(
channel: ChannelNameHsl,
options?: {space: ColorSpaceHsl}
): boolean;
isChannelPowerless(
channel: ChannelNameHwb,
options?: {space: ColorSpaceHwb}
): boolean;
isChannelPowerless(
channel: ChannelNameLab,
options?: {space: ColorSpaceLab}
): boolean;
isChannelPowerless(
channel: ChannelNameLch,
options?: {space: ColorSpaceLch}
): boolean;
isChannelPowerless(
channel: ChannelNameRgb,
options?: {space: ColorSpaceRgb}
): boolean;
isChannelPowerless(
channel: ChannelNameXyz,
options?: {space: ColorSpaceXyz}
): boolean;
/**
* Changes one or more of this color's HWB channels and returns the result.
* Returns a color partway between this color and `color2` according to
* `method`, as defined by the CSS Color 4 [color interpolation] procedure.
*
* [color interpolation]: https://www.w3.org/TR/css-color-4/#interpolation
*
* If `method` is missing and this color is in a rectangular color space (Lab,
* Oklab, RGB, and XYZ spaces), `method` defaults to the color space of this
* color. Otherwise, `method` defaults to a space separated list containing
* the color space of this color and the string "shorter".
*
* The `weight` is a number between 0 and 1 that indicates how much of this
* color should be in the resulting color. If omitted, it defaults to 0.5.
*/
change(options: {
hue?: number;
whiteness?: number;
blackness?: number;
alpha?: number;
}): SassColor;
interpolate(
color2: SassColor,
options?: {
weight?: number;
method?: HueInterpolationMethod;
}
): SassColor;
/**
* Returns a new color that's the result of changing one or more of this
* color's HSL channels.
*
* @throws `Error` if `space` is missing and this color is not in a legacy
* color space (`rgb`, `hsl`, or `hwb`).
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
change(
options: {
[key in ChannelNameHsl]?: number | null;
} & {
space?: ColorSpaceHsl;
}
): SassColor;
/**
* Returns a new color that's the result of changing one or more of this
* color's HWB channels.
*
* @throws `Error` if `space` is missing and this color is not in a legacy
* color space (`rgb`, `hsl`, or `hwb`).
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
change(
options: {
[key in ChannelNameHwb]?: number | null;
} & {
space?: ColorSpaceHwb;
}
): SassColor;
/**
* Returns a new color that's the result of changing one or more of this
* color's Lab channels.
*
* @throws `Error` if `space` is missing and this color is not in the Lab or
* Oklab color spaces.
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
change(
options: {
[key in ChannelNameLab]?: number | null;
} & {
space?: ColorSpaceLab;
}
): SassColor;
/**
* Returns a new color that's the result of changing one or more of this
* color's LCH channels.
*
* @throws `Error` if `space` is missing and this color is not in the LCH or
* Oklch color spaces.
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
change(
options: {
[key in ChannelNameLch]?: number | null;
} & {
space?: ColorSpaceLch;
}
): SassColor;
/**
* Returns a new color that's the result of changing one or more of this
* color's RGB channels.
*
* @throws `Error` if `space` is missing and this color is not in a legacy
* color space (`rgb`, `hsl`, or `hwb`).
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
change(
options: {
[key in ChannelNameRgb]?: number | null;
} & {
space?: ColorSpaceRgb;
}
): SassColor;
/**
* Returns a new color that's the result of changing one or more of this
* color's XYZ channels.
*
* @throws `Error` if `space` is missing and this color is not in an XYZ color
* space.
* @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
* and `1`.
*/
change(
options: {
[key in ChannelNameXyz]?: number | null;
} & {
space?: ColorSpaceXyz;
}
): SassColor;
/**
* This color's red channel in the RGB color space.
*
* @deprecated Use {@link channel} instead.
*/
get red(): number;
/**
* This color's green channel in the RGB color space.
*
* @deprecated Use {@link channel} instead.
*/
get green(): number;
/**
* This color's blue channel in the RGB color space.
*
* @deprecated Use {@link channel} instead.
*/
get blue(): number;
/**
* This color's hue in the HSL color space.
*
* @deprecated Use {@link channel} instead.
*/
get hue(): number;
/**
* This color's saturation in the HSL color space.
*
* @deprecated Use {@link channel} instead.
*/
get saturation(): number;
/**
* This color's lightness in the HSL color space.
*
* @deprecated Use {@link channel} instead.
*/
get lightness(): number;
/**
* This color's whiteness in the HWB color space.
*
* @deprecated Use {@link channel} instead.
*/
get whiteness(): number;
/**
* This color's blackness in the HWB color space.
*
* @deprecated Use {@link channel} instead.
*/
get blackness(): number;
}

22
js-api-doc/value/index.d.ts vendored
View File

@ -19,7 +19,27 @@ export {
CalculationOperation,
CalculationInterpolation,
} from './calculation';
export {SassColor} from './color';
export {
SassColor,
ColorSpaceHsl,
ChannelNameHsl,
ColorSpaceHwb,
ChannelNameHwb,
ColorSpaceLab,
ChannelNameLab,
ColorSpaceLch,
ChannelNameLch,
ColorSpaceRgb,
ChannelNameRgb,
ColorSpaceXyz,
ChannelNameXyz,
ChannelName,
GamutMapMethod,
KnownColorSpace,
PolarColorSpace,
RectangularColorSpace,
HueInterpolationMethod,
} from './color';
export {SassFunction} from './function';
export {SassList, ListSeparator} from './list';
export {SassMap} from './map';

2
spec/EMBEDDED_PROTOCOL_VERSION
View File

@ -1 +1 @@
2.7.1
3.0.0

12
spec/deprecations.yaml
View File

@ -118,6 +118,18 @@ feature-exists:
status: active
deprecated: 1.78.0
color-4-api:
description: Certain uses of built-in sass:color functions.
dart-sass:
status: active
deprecated: 1.79.0
color-functions:
description: Using global color functions instead of sass:color.
dart-sass:
status: active
deprecated: 1.79.0
import:
description: "@import rules."
dart-sass:

27
spec/embedded-protocol.md
View File

@ -259,29 +259,16 @@ the same equality semantics can be generated for a number `x` by rounding
### Colors
The protocol includes three distinct color value types, `RgbColor`, `HslColor`,
and `HwbColor`. In Sass code and custom functions, colors may be represented or
manipulated in either RGB, HSL, or HWB form, so having multiple types allows
whichever form is currently in use to be sent between endpoints without having
to eagerly normalize it.
Colors are represented by the `Color` value type. The API should provide means
of changing one or more channels of a color while leaving other channels as-is.
However, users of the host language API should be able to transparently treat
any color object as though it were either RGB, HSL, or HWB form. The API should
provide access to the red, green, and blue, hue, saturation, lightness,
whiteness, and blackness channels of *every* color object. It should use [this
RGB-to-HSL algorithm], [this HSL-to-RGB algorithm], [this RGB-to-HWB algorithm],
and [this HWB-to-RGB algorithm] to convert between representations as necessary.
Two [legacy colors] are equal if their RGB forms have the same red, green, blue
channels and alpha channels equal rounded to the nearest 1e-11.
[this RGB-to-HSL algorithm]: https://en.wikipedia.org/wiki/HSL_and_HSV#RGB_to_HSL_and_HSV
[this HSL-to-RGB algorithm]: https://www.w3.org/TR/css3-color/#hsl-color
[this RGB-to-HWB algorithm]: https://www.w3.org/TR/css-color-4/#rgb-to-hwb
[this HWB-to-RGB algorithm]: https://www.w3.org/TR/css-color-4/#hwb-to-rgb
Two non-legacy colors are equal if they are in the same color space and their
channel and alpha values are equal rounded to the nearest 1e-11.
The API should also provide means of changing one or more channels of a color
while leaving other channels as-is.
Two colors are equal if their RGB forms have the same red, green, blue channels
and alpha channels within 1e-11 of one another.
[legacy colors]: ../accepted/color-4-new-spaces.md#legacy-color
### Lists

68
spec/embedded_sass.proto
View File

@ -803,62 +803,22 @@ message Value {
repeated string denominators = 3;
}
// A SassScript color value, represented as red, green, and blue channels.
//
// All Sass color values can be equivalently represented as `RgbColor`,
// `HslColor`, and `HwbColor` messages without loss of color information that
// can affect CSS rendering. As such, either endpoint may choose to send any
// color value as any one of these three messages.
message RgbColor {
// The color's red channel. May not be above 255.
uint32 red = 1;
// A SassScript color value.
message Color {
// The name of a known color space.
string space = 1;
// The color's green channel. May not be above 255.
uint32 green = 2;
// The value of the first channel associated with `space`.
double channel1 = 2;
// The color's blue channel. May not be above 255.
uint32 blue = 3;
// The value of the second channel associated with `space`.
double channel2 = 3;
// The color's alpha channel. Must be between 0 and 1,
// inclusive.
double alpha = 4;
}
// The value of the third channel associated with `space`.
double channel3 = 4;
// A SassScript color value, represented as hue, saturation, and lightness channels.
message HslColor {
// The color's hue.
double hue = 1;
// The color's percent saturation. Must be between 0 and 100,
// inclusive.
double saturation = 2;
// The color's percent lightness. Must be between 0 and 100,
// inclusive.
double lightness = 3;
// The color's alpha channel. Must be between 0 and 1,
// inclusive.
double alpha = 4;
}
// A SassScript color value, represented as hue, whiteness, and blackness
// channels.
message HwbColor {
// The color's hue.
double hue = 1;
// The color's percent whiteness. Must be between 0 and 100,
// inclusive. The sum of `whiteness` and `blackness` must not exceed 100.
double whiteness = 2;
// The color's percent blackness. Must be between 0 and 100,
// inclusive. The sum of `whiteness` and `blackness` must not exceed 100.
double blackness = 3;
// The color's alpha channel. Mandatory. Must be between 0 and 1,
// inclusive.
double alpha = 4;
// The color's alpha channel. Mandatory. Must be between 0 and 1, inclusive.
double alpha = 5;
}
// A SassScript list value.
@ -1041,17 +1001,15 @@ message Value {
oneof value {
String string = 1;
Number number = 2;
RgbColor rgb_color = 3;
HslColor hsl_color = 4;
List list = 5;
Map map = 6;
SingletonValue singleton = 7;
CompilerFunction compiler_function = 8;
HostFunction host_function = 9;
ArgumentList argument_list = 10;
HwbColor hwb_color = 11;
Calculation calculation = 12;
CompilerMixin compiler_mixin = 13;
Color color = 14;
}
}

4
spec/js-api/deprecations.d.ts.md
View File

@ -29,7 +29,7 @@
### `Deprecations`
<!-- START AUTOGENERATED LIST -->
<!-- Checksum: bf841a728263bf7efc2a85a091330a1f8074e067 -->
<!-- Checksum: 5470e7252641d3eaa7093b072b52e423c3b77375 -->
```ts
export interface Deprecations {
'call-string': Deprecation<'call-string'>;
@ -49,6 +49,8 @@ export interface Deprecations {
'css-function-mixin': Deprecation<'css-function-mixin'>;
'mixed-decls': Deprecation<'mixed-decls'>;
'feature-exists': Deprecation<'feature-exists'>;
'color-4-api': Deprecation<'color-4-api'>;
'color-functions': Deprecation<'color-functions'>;
import: Deprecation<'import'>;
'global-builtin': Deprecation<'global-builtin'>;
'user-authored': Deprecation<'user-authored', 'user'>;

18
spec/js-api/index.d.ts.md
View File

@ -82,7 +82,25 @@ export {
CalculationOperation,
CalculationOperator,
CalculationValue,
ChannelName,
ChannelNameHsl,
ChannelNameHwb,
ChannelNameLch,
ChannelNameLab,
ChannelNameRgb,
ChannelNameXyz,
ColorSpaceHsl,
ColorSpaceHwb,
ColorSpaceLch,
ColorSpaceLab,
ColorSpaceRgb,
ColorSpaceXyz,
GamutMapMethod,
HueInterpolationMethod,
KnownColorSpace,
ListSeparator,
PolarColorSpace,
RectangularColorSpace,
SassArgumentList,
SassBoolean,
SassCalculation,

1128
spec/js-api/value/color.d.ts.md
View File

File diff suppressed because it is too large Load Diff

22
spec/js-api/value/index.d.ts.md
View File

@ -22,7 +22,27 @@ export {
CalculationOperation,
CalculationInterpolation,
} from './calculation';
export {SassColor} from './color';
export {
SassColor,
ColorSpaceHsl,
ChannelNameHsl,
ColorSpaceHwb,
ChannelNameHwb,
ColorSpaceLab,
ChannelNameLab,
ColorSpaceLch,
ChannelNameLch,
ColorSpaceRgb,
ChannelNameRgb,
ColorSpaceXyz,
ChannelNameXyz,
ChannelName,
GamutMapMethod,
KnownColorSpace,
PolarColorSpace,
RectangularColorSpace,
HueInterpolationMethod,
} from './color';
export {SassFunction} from './function';
export {SassList, ListSeparator} from './list';
export {SassMap} from './map';