Support banners/headers

[wbamberg]

There's a class of KS macros that we call "banners" or "headers".

They create a block element across the page warning that the item is (for example) deprecated. See e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Expression_closures for a nice pile of these things.

At the moment, in Kuma, the fact that a method is deprecated is maintained in two (or more) places: the BCD for the item (under the status key) and the macro call itself. This makes our content hard to maintain.

We would like to maintain this info only in BCD, and have the stumptown-renderer automatically add the relevant banner(s) based on the BCD.

Since stumptown-renderer already gets BCD for each item, it can do this with no changes to stumptown-content. We might anyway choose to represent status more explicitly in the built JSON, via a top-level status property, say. Then there would be a small change to stumptown-content to add this.

Acceptance criteria

• stumptown-renderer automatically adds "Deprecated", "Non-standard", or "Experimental" banners to pages, based on the information from BCD.

[peterbe]

So this is one of those less-than-trivial areas when/if we switch stumptown-renderer to be about displaying and rendering Kuma HTML.

By the way, this is how that would look like in Yari:

I'd love to develop another ingredient React component but whether it should be used should ideall come from the array of sections.

So, I think there should be something like

console.log(doc.sections.slice(0, 2))
// [{
//    "title": "Non-standard",
//    "content": "<p>This feature is non-standard and ...
//  },
//  {
//    "title": "Obsolete since Gecko 60 (Firefox 60 / Thunderbird 60 / SeaMonkey 2.57)",
//    "content": "<p>This feature is obsolete. Although it 
//  }] 

Note-to-self; here's what the Kuma HTML looks like this page that page:

<div>{{JSSidebar("Operators")}}{{Non-standard_Header}}{{Obsolete_Header("gecko60")}}
<div class="warning"><strong>Non-standard. Do not use!</strong><br>
The expression closure syntax is a deprecated Firefox-specific feature and has been removed starting with Firefox 60. For future-facing usages, consider using <a href="/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">arrow functions</a>.</div>
</div>

So, apart from the sidebar, some of those things are KS macros and some are "plain prose content".

[wbamberg]

It would be better if the JSON from stumptown-content contained just the data, not the HTML, and the renderer decided how to present that data to the user. This is in line with how we do it for other things we treat as data, like BCD (where we provide the JSON, not the rendered table) or specifications (where we provide the spec link and don't say how to present it.

That also makes it easier for other potential users of stumptown-content to use the content.

If it's important to the render to provide the content in a way the follows the order of items in the body, then the stumptown-content JSON could include an item like:

{
    "type": "status",
    "value": [
        "non-standard", "deprecated"
    ]
}

[peterbe]

I'm cool with that.

I can write an ingredient that does what kumascript/macros/ObsoleteGeneric.ejs does.

[peterbe]

Perhaps @kenrick95 would be interested?
We basically need a React component that can take an array like this ["non-standard", "deprecated"] and it should produce something like this:

The macro https://github.com/mdn/kumascript/blob/master/macros/ObsoleteGeneric.ejs combined with https://github.com/mdn/kumascript/blob/master/macros/Obsolete_Header.ejs should be the inspiration. Together with https://github.com/mdn/kumascript/blob/master/macros/Non-standardGeneric.ejs for non-standard.

If you do get a chance @kenrick95 avoid localization and just go for plain English. We'll make these React ingredients localized some other day.

[wbamberg]

I think it's still up for discussion exactly how this will look in the JSON (see mdn/stumptown-content#306, where this would get sorted out) but a couple of things:

• there would be three possible things to indicate: "deprecated", "experimental", and "non-standard". So no separate "obsolete" (BCD doesn't distinguish "deprecated" and "obsolete" because nobody knows the difference anyway).
• there would be no reference to Gecko versions, or any versions.

[peterbe]

Now moot.