Allow relabeling and multiple kinds of "best practice"

[jyasskin]

In https://w3ctag.github.io/privacy-principles/ we're using the <div class=practice> system to capture the principles in a way that'll let us create a summary section. However, there's no way to label them "Principles" instead of "Best Practices".

We also might want to describe a real "best practice" that's not a "principle", so being able to have multiple of this kind of list could be useful.

@darobin

[darobin]

I wonder if we could treat this as a form of general "callout." The features for a callout are:

• A specific box style
• A title (and perhaps numbering)
• A generated section listing them all

This could be specified with a configuration entry thusly:

callouts: {
  principle: 'Principle',
  warning: {
    label: 'Careful!',
    sectionLabel: 'List of bad things',
    color: 'orange',
  },
}

The idea being that if you just give a string you get that as the label, default box colour, and the section labelled with "List of {{Automatic Plural}}". Or something like that.

I defer to @marcoscaceres on the design as I know some of the approach has changed since my time.

[marcoscaceres]

Yeah, I definitely want to just have specific callouts (using a custom element or a <aside class="box whatever" title="The box!">)... just need to get around to adding them.

[sidvishnoi]

Or maybe a custom element (that converts itself to regular markup):

<rs-callout type="best-practice">
  <h2>Best practice</h2> <!-- optional, depends on "type" attribute" -->
  <p>Practice makes perfect, but perfect is the enemy of the good.</p>
</rs-callout>

Edit: Oh, you did say custom element.

[darobin]

I'm fine with the custom element route, but people should be able to use this functionality without it being built-in and without having to retype the title every time. Is your thinking that you could configure new callout types using for instance metas? And get them listed with `"?

Also, is the idea to implement this with an actual CE (and serialise its DOM at save time) or to just YOLO transform the DOM?

[marcoscaceres]

I’d prefer to just use regular HTML as these boxes don’t really need any heavy transforms. We also have precedence with issues, notes, etc. using regular html.

[jyasskin]

One nit: I don't think these are <aside>s, unlike notes and examples. For principles, especially, they're normative and at least as core to the document as the text around them. <div> seems fine, although these could be <figure>s.

[marcoscaceres]

@jyasskin, good point... supporting figure is interesting, but it could just be a child of the div. I think we'd probably want to stick with the current model of allowing:

• <p>
• <div>
• <aside> ... (maybe discourage this... but I think people will have "opinions" about the right semantics)