[css-typed-om] Inputs for the CSSColorValue constructors

[tabatkins]

I'm writing the spec for color values right now, and the overall structure is straightforward: a CSSColorValue superclass, and subclasses for each type of color function.

I'm struggling a bit with the best design for the constructor arguments and/or the shorthand functions.

Some arguments, like hue angles, are easy - they're just a CSSNumericValue that needs to match <angle>. But most of the arguments to color functions are percentages. Obviously I'll accept a CSSNumericValue that matches <percentage>, but I'd like easier ways to invoke these - writing new CSSRGB(CSS.percent(10), CSS.percent(0), CSS.percent(100)) isn't great.

In particular, I'd like to allow them to accept JS numbers, interpreting the range 0-1 as being equivalent to a percent between 0% and 100%, so you could instead write the preceding function as new CSSRGB(.1, 0, 1).

This would generally be unproblematic and straightforward, except that rgb() accepts <number> as well, in the range 0-255. And elsewhere in TypedOM (such as new CSSScale()), passing a raw JS number is equivalent to passing a CSSUnitValue(x, "number") (see the "rectify a numberish value" algo). So this leaves me with several possibilities, none of which I find great:

1. Always allow JS numbers in the color functions in the 0-1 range. There's no constructor form that's a direct equivalent to the rgb(0, 128, 255) syntax.

2. Allow JS numbers in the color functions in the 0-1 range, but also allow CSSUnitValue(x, "number") to be passed to CSSRGB, with the 0-255 range.

3. Don't allow JS numbers at all, only CSSNumericValues. CSSRGB accepts CSSUnitValue(x, "number") in the 0-255 range.

4. (Definitely bad, not doing this) Allow JS numbers in the 0-1 range for all the color functions except CSSRGB, allow them in the 0-255 range for CSSRGB (in addition to CSSUnitValue(x, "number")).

5. Same as (3), but also have shorthand functions like CSS.rgb() (akin to the CSS.px() family for numeric values) that act like (1).

I'm considering going with (1), but (5) would be fine as well. I don't like the others very much. Anyone else have opinions?

[tabatkins]

Oh, forgot to list the big downside of (1) - if you wanted to make a lookalike custom function for rgb() that took 0-255 arguments (in the CSS) in the same way, you'd have to remember to translate any "number" arguments into JS numbers, rather than passing them thru directly.

Well, calling it "big" is perhaps a bit much, but it's the largest downside for (1), at least.

[plinss]

Another option (and a bit more modern JS) could be to use a dictionary initializer as a single argument to the constructor. It also buys you some extensibility and flexibility.

Something like: CSSRGB({r: 0, g: 128, b: 255}) or CSSRGB({rPct: 0, gPct: 50, bPct: 100}) (not personally a fan of the abbreviation but trying to keep it succinct)

[svgeesus]

@LeaVerou the design decisions for color.js seem directly relevant here, so given your expertise in API design I look forward to your comments.

My expertise is more on the functionality, rather than the API surface.

[svgeesus]

In particular, I'd like to allow them to accept JS numbers, interpreting the range 0-1 as being equivalent to a percent between 0% and 100%, so you could instead write the preceding function as new CSSRGB(.1, 0, 1).

That is mostly going to work, except of course for CIE Lightness where 100% maps to 100, not 1.

[LeaVerou]

This is a very common issue with any library working with RGB colors. Typically the decision is to go with one of the two and if one wants to use a different range, they need to convert. In Color.js we went with 0-1 for reasons I will detail below, chroma.js and d3 Color went with 0-255.

I would suggest going with numbers in the 0-1 range, as the 0-255 range is a relic. It originates in using 8 bit for each color component, and seems completely arbitrary otherwise. Note that rgb() is not restricted to 8 bit anymore as it can accept non-integers. Also, all of the new RGB-based colors in Color 4 use 0-1 as well, including color(srgb). The more using > 8 bit per component becomes commonplace, the more arbitrary 0-255 will seem. 0-1 future-proofs this API.

Something like: CSSRGB({r: 0, g: 128, b: 255}) or CSSRGB({rPct: 0, gPct: 50, bPct: 100}) (not personally a fan of the abbreviation but trying to keep it succinct)

This creates unnecessary error conditions: what happens when both r and rPct are specified?

Stepping back for a bit, speccing Typed OM for colors is a fairly substantial undertaking and it would be good if we could get some consensus on the overall architecture and design decisions before discussing the minutiae of constructor arguments. I know there are many people in the group who would have input on said design decisions and would love to partake, myself and @svgeesus included.

[plinss]

Something like: CSSRGB({r: 0, g: 128, b: 255}) or CSSRGB({rPct: 0, gPct: 50, bPct: 100}) (not personally a fan of the abbreviation but trying to keep it succinct)

This creates unnecessary error conditions: what happens when both r and rPct are specified?

That could be trivially resolved. You either raise an exception or decide which one wins.

Using an initialization dictionary also allows you to mix and match, e.g. CSSRGB({r: 0, gPct: 50, b: 42})

That said, I agree that 0-255 is a relic, but it is in common use. I'm in favor of making the API more forward-looking, but want to maintain backward compatibility with legacy code as well to ease the transition. I'm also concerned that if we go with pure 0-1 floating point that we make sure all the (0-255)/255 values can be accurately represented by JS numbers so they at least can round-trip without rounding errors (I think that's the case, but someone should check). e.g. if someone does new CSSRGB(42/255, 42/255, 42/255) and we have an accessor that returns a color channel in the 0-255 range, it needs to return 42, not 42.0000001 or 41.99999999. There's also the question of how these serialize, would the preceding example serialize as rgb(42, 42, 42) or rgb(16.47%, 16.47%, 16.47%)? css-color-4 specifies the former.

Even if we decide that the only values are r, g, and b in the 0-1 range, using an initialization dictionary is more readable, and is much more future-proof. It's simply a more forgiving pattern. Not to mention, it's endorsed by the TAG: https://www.w3.org/TR/2020/NOTE-design-principles-20201110/#prefer-dict-to-bool and https://www.w3.org/TR/2020/NOTE-design-principles-20201110/#naming-optional-parameters

Actually, the more I think about the serialization issue, the more I think the CSSRGB constructor should only take values comparable with the CSS rgb() function. This is an object model meant to represent the rgb() function as it stands after all, not an opportunity to invent something new. So I'm voting in favor of option 4 above (with a dictionary constructor, and the ability to take percentages as well as numbers in the 0-255 range). New ways of defining colors should be used in classes that represent the CSS constructs that allow them, e.g. CSSColor() that takes arguments like color() does.

[svgeesus]

In Color.js we went with 0-1 for reasons I will detail below, chroma.js and d3 Color went with 0-255.

chroma.js and d3 Color are both sRGB-only, so that was a reasonable decision at the time but will bite them once they extend to other RGB spaces.

Some spaces, like rec2020 and rec2100, don't even allow 8 bits per component; the choices are 10, or 12 (recommended). Also, when quantized, there are two encoding ranges (narrow and wide) but the float 0..1 representation is always wide, which removes one source of error. For example, in 10 bit narrow-range encoding, color component values range from 64 to 940; in 12 bit narrow-range encoding, they range from 256 to 3760.

[maltenuhn]

(first contribution, hi! and apologies for any conventions I'm breaking). Design / dev tool author here. I favour (1) for the same reasons as @tabatkins and @LeaVerou Lea (0-255 is legacy, 0-1 is computationally simpler).

Some additional data points / perspectives:

• from user interviews we know that for many developers / designers, rgb 0-255 often results in mental estimations such as "how far along the scale from from eg "no red" to "red" do I want to be. (That's not to say there isn't a lot of muscle memory here)
• It's also more similar to the way other colour spaces are already expressed (eg the 's' and 'l' of hsl / hsv). We see these becoming more popular for obvious reasons (esp. in an age of design systems / computational color scheme generation)
• Additionally: Safari (proprietarily) already exposes the P3 colour space with 0-1 for rgb. I wrote something up here a year ago that has some details. (update: the official webkit docs )

[LeaVerou]

Something like: CSSRGB({r: 0, g: 128, b: 255}) or CSSRGB({rPct: 0, gPct: 50, bPct: 100}) (not personally a fan of the abbreviation but trying to keep it succinct)

This creates unnecessary error conditions: what happens when both r and rPct are specified?

That could be trivially resolved. You either raise an exception or decide which one wins.

Indeed, you can solve all unnecessary error conditions by raising an error, but that doesn't make them good practice. It's far better to avoid creating the error condition in the first place.
Deciding which one wins is the kind of arbitrary decision that makes APIs feel unpredictable and hard to learn.

Using an initialization dictionary also allows you to mix and match, e.g. CSSRGB({r: 0, gPct: 50, b: 42})

That said, I agree that 0-255 is a relic, but it is in common use. I'm in favor of making the API more forward-looking, but want to maintain backward compatibility with legacy code as well to ease the transition. I'm also concerned that if we go with pure 0-1 floating point that we make sure all the (0-255)/255 values can be accurately represented by JS numbers so they at least can round-trip without rounding errors (I think that's the case, but someone should check). e.g. if someone does new CSSRGB(42/255, 42/255, 42/255) and we have an accessor that returns a color channel in the 0-255 range, it needs to return 42, not 42.0000001 or 41.99999999.

I just ran for (let i=0; i<256; i++) { let a = i/255; console.log(a * 255); } and it seems to only log integers. Not sure if there's a compiler optimization at play though.

Even if we decide that the only values are r, g, and b in the 0-1 range, using an initialization dictionary is more readable, and is much more future-proof. It's simply a more forgiving pattern. Not to mention, it's endorsed by the TAG: w3.org/TR/2020/NOTE-design-principles-20201110/#prefer-dict-to-bool and w3.org/TR/2020/NOTE-design-principles-20201110/#naming-optional-parameters

Please note that the TAG guidelines you link to (both of which I'm aware of and have even taught) do not apply here. They are both about optional arguments, which these are not. Also, the first one is mainly about booleans, edited recently to generalize to all optional primitives. Indeed, avoiding boolean positional arguments is one of the most basic API design principles (they are called "boolean traps" for good reason). However, red, green, and blue, are numbers with an established meaning, an established order, and all of which are mandatory.

That said, there is less of an established order in other color spaces (e.g. LCH vs HCL), so for consistency, it would make sense to use named parameters here too.

[LeaVerou]

(first contribution, hi! and apologies for any conventions I'm breaking). Design / dev tool author here. I favour (1) for the same reasons as @tabatkins and @LeaVerou Lea (0-255 is legacy, 0-1 is computationally simpler).

Hi @maltenuhn! Welcome! 👋🏼

Some additional data points / perspectives:

• from user interviews we know that for many developers / designers, rgb 0-255 often results in mental estimations such as "how far along the scale from from eg "no red" to "red" do I want to be. (That's not to say there isn't a lot of muscle memory here)

That's fascinating. Do you have a source for these user interviews? I would love to read more about this study!

• Additionally: Safari (proprietarily) already exposes the P3 colour space with 0-1 for rgb. I wrote something up here a year ago that has some details. (update: the official webkit docs )

Not proprietary, but perfectly valid CSS Color 4 syntax! Unfortunately, they only implemented part of it, no other spaces besides P3, and no actual <percentage> values.

[plinss]

Indeed, you can solve all unnecessary error conditions by raising an error, but that doesn't make them good practice. It's far better to avoid creating the error condition in the first place.

We can make many more APIs avoid errors by severely restricting what they can do, that doesn't help authors either. There's a balance needed. Allowing authors more flexibility at the risk of allowing them to make mistakes is a common trade off.

Please note that the TAG guidelines you link to (both of which I'm aware of and have even taught) do not apply here.

The principles they represent do apply.

They are both about optional arguments, which these are not.

First, there is an optional argument to the CSS rgb() function that we seem to be forgetting about here, a.
Second, there's no reason to make all the arguments mandatory, new CSSRGB({g:128}) could (and should) be equivalent to new CSSRGB({r: 0, g: 128, b: 0, a: 1}).

Also, the first one is mainly about booleans, edited recently to generalize to all optional primitives.

It used to be about booleans, and despite the anchor (which was left intact to not break links) now talks about the general case, which is why I included the link (and the links were for the benefit of other readers of the thread, I'm aware that you know them).

---

Back to Tab's original question, I'm now fairly well convinced that bare numbers passed into the constructor of a CSSRGB object (regardless of how they're passed) should be interpreted the same as bare numbers passed into CSS rgb(). This is an object model of the CSS rgb() function, it needs to match the semantics of the rgb() function. Full stop. I have no issue with convenience functions or conversions from other types that take 0-1 numbers, but will strongly object to redefining the semantics of the rgb() function in the object model. It should be all about modeling the rgb() function as it exists, not about creating a new general purpose color object (which I'm in favor of, and agree should use 0-1 numbers). Similarly, object models of other CSS color functions should accept the same arguments as their CSS equivalents.

[tabatkins]

Using an initialization dictionary also allows you to mix and match

We have numeric types already for precisely this reason - if you want percentages, you can just pass a CSS.percent(10) as the value.

I don't think an initialization dict, in general, is the best pattern here - most of the arguments are required, and there's already a well-known and established order for them, coming from CSS (and re-expressed right in the name). So I'm pretty confident positional is still the right way to go here, at least for the simple functions. (color() might get a different treatment.)

So I'm voting in favor of option 4 above

Given that taking raw numbers is a pure convenience (rather than only taking the CSSStyleValue objects that it'll expose post-construction), I'm really loathe to do tricky stuff like that and have the numbers be interpreted in different ways depending on the function. It's just begging for people to hold wrong. My current spec text is doing option 2 (raw JS numbers are always 0-1 percentages, but CSSRGB accepts CSS.number(127) as well).

[plinss]

Using an initialization dictionary also allows you to mix and match

We have numeric types already for precisely this reason - if you want percentages, you can just pass a CSS.percent(10) as the value.

Fair enough.

I don't think an initialization dict, in general, is the best pattern here - most of the arguments are required, and there's already a well-known and established order for them, coming from CSS (and re-expressed right in the name). So I'm pretty confident positional is still the right way to go here, at least for the simple functions. (color() might get a different treatment.)

I disagree. I have no issue with also accepting positional arguments. But I want to push back on them all being required. e.g. does let x = new CSSRGB() throw an exception or is it simply new CSSRGB(0, 0, 0). Similarly, what if an author calls new CSSRGB(42) should that throw or just be new CSSRGB(42, 0, 0)?

So I'm voting in favor of option 4 above

Given that taking raw numbers is a pure convenience (rather than only taking the CSSStyleValue objects that it'll expose post-construction), I'm really loathe to do tricky stuff like that and have the numbers be interpreted in different ways depending on the function. It's just begging for people to hold wrong. My current spec text is doing option 2 (raw JS numbers are always 0-1 percentages, but CSSRGB accepts CSS.number(127) as well).

But that's actually inconsistent with your "passing a raw JS number is equivalent to passing a CSSUnitValue(x, "number")" so will cause even more author confusion IMO. I see no reason why new CSSRGB(100, 150, 200) should yield any different result than rgb(100, 150, 200) in CSS. Anything else is asking for trouble. As I said, we're modeling the existing rgb() function here, not inventing something new.

Frankly if you interpret bare numbers as 0-1 you are doing something tricky and interpreting them in a different way for this function, interpreting 0.5 as equivalent to CSS.number(127) rather than CSS.number(0.5) like you do everywhere else.

So let me make a concrete proposal:

dictionary CSSRGBInit {
    CSSNumberish r = 0; 
    CSSNumberish g = 0; 
    CSSNumberish b = 0;
    CSSNumberish a = 1; 
};
interface CSSRGB {
    constructor(optional CSSNumberish r = 0, optional CSSNumberish g = 0, optional CSSNumerish b = 0, optional CSSNumberish a = 1);
    constructor(optional CSSRGBInit init = {});
    ...
};

Both bare numbers and CSS.number() are interpreted the same as if they were specified in rgb().

This allows for author convenience, is succinct, is consistent with CSS and should be consistent with other CSS color object constructors.

(I don't have an issue if you want to make a new type restricting the values to double (or even octet), number, and percent types, rather than CSSNumberish, or just define other values to throw exceptions.)

[LeaVerou]

We can make many more APIs avoid errors by severely restricting what they can do, that doesn't help authors either. There's a balance needed. Allowing authors more flexibility at the risk of allowing them to make mistakes is a common trade off.

True, though I'm not convinced saving the user one division with 255 is a worthy trade off.

Please note that the TAG guidelines you link to (both of which I'm aware of and have even taught) do not apply here.

The principles they represent do apply.

Both Tab and I have explained why they do not:

1. all arguments (besides a) are required (assigning an arbitrary default can theoretically make any argument optional, but in this case that's externally inconsistent)
2. There is a very well established order, and arguments never/rarely need to be provided in a different order.

Back to Tab's original question, I'm now fairly well convinced that bare numbers passed into the constructor of a CSSRGB object (regardless of how they're passed) should be interpreted the same as bare numbers passed into CSS rgb(). This is an object model of the CSS rgb() function, it needs to match the semantics of the rgb() function. Full stop. I have no issue with convenience functions or conversions from other types that take 0-1 numbers, but will strongly object to redefining the semantics of the rgb() function in the object model. It should be all about modeling the rgb() function as it exists, not about creating a new general purpose color object (which I'm in favor of, and agree should use 0-1 numbers). Similarly, object models of other CSS color functions should accept the same arguments as their CSS equivalents.

You feel so strongly that the function should mirror the semantics of rgb(), yet you are opposed to it using positional arguments, just like rgb(). 🤔

Please note that color(srgb) uses the 0-1 range when provided with bare numbers. Are we really going to have two different sRGB objects with components in different ranges?