Browser compatibility tables for API overviews

MDN
#1

Ideally, our API overview pages ought to have a specification table box on them, and in many cases we have them. The problem is that because we don’t have a concept of “this API overall” in BCD, you have to compromise, often by picking an important or the most important thing in the API and using that.

It would be nice to have a way to state the compatibility in general this way for overview pages, either as a simple “it’s there in this browser and this one but not that one” sort of way or as a more intricate set of supported vs. unsupported subfeatures. I don’t really know which is best (and really am not all that strongly aligned one way or another), but having a responsible and standard way to do compat tables on overviews would be helpful.

1 Like
#2

This is an interesting point. I’ve started recommending that people just write a general summary of where the API is at, for example

But it would be nice to have some kind of more formal way to do this.

1 Like
#3

That doesn’t seem like it’d scale very well, and wouldn’t it probably lead to outdated info?

1 Like
#4

I agree; that seems like it’s just begging for content to go obsolete quickly and without notice. A way to handle this using BCD would be helpful. Maybe adding an APISupport.json file containing an array of objects, each of which is labeled with one of our spec names (as in GroupData.json), and with each record containing an array of browsers and their support overview data.

I could see this file being either maintained manually or generated periodically using a script that uses the list of things in GroupData.json for that spec to look at each interface and for each item in that interface’s BCD JSON file, compute the percentage of the entries that are supported for the browser. Use that to generate the support status for that API.

A similar algorithm could be used for the compat bar, of course, when we get to that.

Either way, once we have the data, we can update the Compat macro so it can generate an appropriate “overall support” table for an API, given the API’s name.

#5

Yes, I agree with Connor. A big original motivation for moving compat info into data is to avoid having compat info in more than one place. Another is to enable aggregate views of the data.

There are a couple of options at the moment.

Otherwise, if you want to have an “overview” for a thing that isn’t represented at all in the BCD structure (such as a CSS module) then yes, as @sheppy says, you need something that describes which individual things comprise that overall thing. This is the approach taken by the CompatGroup macro (https://github.com/mdn/kumascript/pull/650) which @ddbeck and @eduardoboucas wrote in Paris, that never got merged :(.

It does seem like in general: if you want custom BCD overview tables, you need a maintainable single place you can say “this big thing maps onto all those little things” - and this sounds like it’s not BCD-specific - you might need it for things like sidebars or even to build indexes of links to the little things in the page, or lists of the specifications that define the little things.

In our present situation I’d be wary of handling this by adding a bunch of extra metadata and KS macros to process it though, without having some idea of what this might look like in a future version of Kuma.

#6

Yes, certainly that would need to be kept in mind.

1 Like
#7

I’d like to point towards:
https://github.com/mdn/browser-compat-data/issues/1243

https://github.com/mdn/kumascript/pull/650

#8

I agree that what I’m doing isn’t great. But for web components doing what Will suggested would be really messy; I suppose maybe it would work to just include a couple of tables to indicate the support level of the two most central pieces (e.g. custom elements and shadow dom)?

For the CSS logical properties page, I’m not sure what you’d do; there are about 80 properties, and the level of support is not very obviously split.

1 Like
#9

Well, you could use a similar algorithm to what the CSSRef macro does to determine which CSS properties belong to which group, but that will require extracting the compat macro rendering code from the {{Compat}} macro, which depends on:

#10

So, I would say that I think we should consider how many things we’ve run into where these monolithic macros are causing us headaches, and that it’s time that we do something about it. I think we should find things that can be, essentially, turned into library functions. Things like collecting information about a group of pages, generating a section of sidebar content from a list of links and titles, etc.

With a library along those lines we could probably dramatically improve our macro complexity issues while also making it easier to update existing macros, create new macros, and test them all properly.

#11

So resurrect my work on browser‑compat‑toolkit?