search

w3ctag / design-principles

A small-but-growing set of design principles collected by the TAG while reviewing specifications
https://w3ctag.github.io/design-principles
176 stars 46 forks source link

Web platform design principle on attribute <- -> IDL attribute reflection (principle 3.5 Keep attributes in sync) #424

Closed prushforth closed 1 year ago

prushforth commented 1 year ago

We are designing a speculative polyfill for a map viewer element. Currently, we have specified lat, lon and zoom attributes that allow the author to specify the starting location and scale of the map. Also currently, we reflect the lat/lon/zoom of the map to these attributes, and ignore changes to them. The only way that script can change their values (and the state of the map), is to use the IDL method zoomTo(lat,lon,zoom). The user is able to pan and zoom the map interactively , so this forms a key source of updates to these values, not just script. In regard to reflection, we seem to follow the advice of princple 3.5. We also want to be consistent, per principle 2.4.

Our question is, should we (re-)design these attributes to be more like input.value wherein the initial value is obtained from the <input value="..."> attribute (which never changes after document load), but thereafter script can read or set the value of the same name as the attribute (that is not reflected) via the input.value IDL attribute (which is called a 'counterpattern' in this principle -- aside: Is a counterpattern the same as an antipattern?), OR, should we re-design these attributes to reflect the map's initial lat/lon/zoom characteristics, and force the setting / getting of these values through other, differently named IDL attributes. The latter pattern seems like <video muted>, HTMLMediaElement.defaultMuted + HTMLMediaElement.muted, which seems to be a bit in both worlds - the muted attribute is reflected by the defaultMuted setter, but HTMLMediaElement.muted controls the player volume and perhaps user interface state, and has the same name but does not reflect to the muted content attribute. Except for reflecting the map viewer state to the lat/lon/zoom attributes which initialize the viewer, our current design follows this pattern in one way: we provide a differntly-named IDL method to allow script to set and reflect to, respectively, (all three) IDL and content lat/lon/zoom attributes, and to simultaneously set viewer state, similar to HTMLMediaElement.muted (which sets player state). We could add IDL attributes of different names to set the lat/lon/zoom content attributes.

Generally I understand principle 3.5 to apply to attributes that "aren't (too) interactive" i.e. if script changes the IDL attribute, that's one source of update/ state, but if the user can change the underlying characteristic through gestures, typing etc., maybe the attributes shouldn't update / they should be considered "initial" values, like <input value>?

Thanks for your work, and your consideration of this question.

prushforth commented 1 year ago

I think we have found a path. Happy for any comments. Sorry to bother you.