The Web Preference API aims to provide a way for sites to override the value for a given user preference (e.g. color-scheme preference) in a way that fully integrates with existing Web APIs.
Do we need a clearOverride method? Could we just use setOverride with a value of null or undefined?
Yeah, I think just making them nullable works fine, especially if the value is meant to be interpreted as "the overriding value" not "the current value" (which can be obtained from matchMedia()).
Do we need a clearAllOverrides method?
So long as authors can enumerate the available overrides so they can clear them all themselves, nah. It doesn't seem like a common enough use-case to need explicit API for.
Do we need a way to get the preference value or is using matchMedia sufficient? (I think we need at least a getOverride method)
MQs aren't defined to have "a value", they're defined purely in terms of queries that can be true or false; the actual underlying state can be complex, and multiple queries can be true at once. The preference MQs are probably reasonable to treat as having a specific value, but I'm not sure we want to commit to locking them into that interpretation. I'd probably avoid this and just allow getting the current override value.
Do we need an API method to indicate the accepted values for a given preference?
The author can just set whatever value they want and check for an error, so exposing the acceptable values would just be a nice convenience. That said, I think it would be reasonable.
Do we need a user activation requirement for set and clear? (e.g. clicking a button) This would remove the ability to automatically sync preferences.
Do we need a permission grant? Or at least integrate with permissions policy?
No, this is purely a convenience feature for devs. A dev can always ignore the preference media queries and just do whatever styling they want, or use JS to query the preference MQs and pipe the result into a class on body. This feature offers zero power over those existing methods, and so requires no additional care.
Do we need configuration for the scope of these overrides?
As in, "just this page" versus "this page and all descendant frames"? Probably not; if the preference comes directly from the user rather than an override, it'll be all frames anyway. I don't see why the user choosing dark mode in the page's UI vs the browser's UI makes a difference here. (But if someone does have a good use-case, it wouldn't be unreasonable.)
Do we need configuration for choosing session vs permanent override?
Unless there's a good use-case for session-based, I'd avoid this complexity.
Yeah, I think just making them nullable works fine, especially if the value is meant to be interpreted as "the overriding value" not "the current value" (which can be obtained from
matchMedia()).So long as authors can enumerate the available overrides so they can clear them all themselves, nah. It doesn't seem like a common enough use-case to need explicit API for.
MQs aren't defined to have "a value", they're defined purely in terms of queries that can be true or false; the actual underlying state can be complex, and multiple queries can be true at once. The preference MQs are probably reasonable to treat as having a specific value, but I'm not sure we want to commit to locking them into that interpretation. I'd probably avoid this and just allow getting the current override value.
The author can just set whatever value they want and check for an error, so exposing the acceptable values would just be a nice convenience. That said, I think it would be reasonable.
No, this is purely a convenience feature for devs. A dev can always ignore the preference media queries and just do whatever styling they want, or use JS to query the preference MQs and pipe the result into a class on
body. This feature offers zero power over those existing methods, and so requires no additional care.As in, "just this page" versus "this page and all descendant frames"? Probably not; if the preference comes directly from the user rather than an override, it'll be all frames anyway. I don't see why the user choosing dark mode in the page's UI vs the browser's UI makes a difference here. (But if someone does have a good use-case, it wouldn't be unreasonable.)
Unless there's a good use-case for session-based, I'd avoid this complexity.