mirror of
https://github.com/sass/sass.git
synced 2024-09-21 02:27:30 +00:00
Merge pull request #3930 from sass/feature.color-4
Merge feature.color-4 into main
This commit is contained in:
commit
0150d3861d
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
File diff suppressed because it is too large
Load Diff
16
js-api-doc/deprecations.d.ts
vendored
16
js-api-doc/deprecations.d.ts
vendored
@ -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
18
js-api-doc/index.d.ts
vendored
@ -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
572
js-api-doc/value/color.d.ts
vendored
@ -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
22
js-api-doc/value/index.d.ts
vendored
@ -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';
|
||||
|
@ -1 +1 @@
|
||||
2.7.1
|
||||
3.0.0
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
||||
|
@ -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;
|
||||
}
|
||||
}
|
||||
|
||||
|
@ -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'>;
|
||||
|
@ -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,
|
||||
|
File diff suppressed because it is too large
Load Diff
@ -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';
|
||||
|
Loading…
Reference in New Issue
Block a user