The specific use case where we ran into this was adding a button to section headings in T336692: Tool to summarise sections on a wiki page , which had to be done in several different ways for different skins and talk vs. article page. (cc @Alexey_Skripnik who did that work.)

I wonder if the work @matmarex is doing would lend itself to this kind of API?

How so?

In T337286#9394308, @matmarex wrote:

How so?

The work in T13555 is changing the heading HTML so I assume any gadgets appending to the heading are likely to be broken/impacted. This might be a good opportunity to create and advertise a helper function e.g. mw.util.addHeadingLink( 'First_heading', node );

No worries if not, just a passing thought.

Given the issue in T358452 and some of the recent gadget breakage I am a little worried about code interacting with section headings and would feel more comfortable with an API that is compatible with both the old and new HTML. Would the content transform be interested in prioritizing this work as part of the section heading changes in T13555? Perhaps the web team and content transform team could work together on this one as part of a solution to T358452 ?

Here's some napkin pseudo code that might be useful to create and allow access and safe manipulation of sections.

interface Section {
   constructor() {
      /** HTMLElement representing heading associated with section */
     const heading
     /** @type {number} of associated section */
     const editSection;
     /** HTMLElement|null representing section tag - null in legacy parser */
    const element;

   /** Allows creation of actions alongside edit link */
    createNewAction( label, iconName ) {
        return HTMLElement;
   }
}

// returns an array of all Sections representing headings.
const sections = mw.util.getSections();

// returns element matching CSS selector
const section = mw.util.getSections( '#id' )[0];
const sectionsH3Only = mw.util.getSections( 'h3 );

@ssastry this is the task we discussed today. If we (perhaps with @matmarex ) could work on this in early April, we think it would mitigate various problems we'll see in MobileFrontend and will soften the blow of gadgets breaking (which often web team is blamed for). MobileFrontend will likely change the HTML format further to support section collapsing for example so having a stable API seems like a good thing for both our teams on the long run.

If you want to work on this, I think it needs to start with inventorying the existing gadgets to inform the design of the new API. Otherwise we risk spending time on something that doesn't actually serve the practical use cases. Until that happens, we need to continue supporting the de facto API of the .mw-editsection CSS class and associated markup.

@matmarex yes that would be a good starting point. A specification of what's needed would be useful.

A crude global search suggests there are about 1,548 gadgets/user scripts that might be impacted e.g. reference h2 nodes:
https://global-search.toolforge.org/?q=%5B%27%22%5Dh2&regex=1&namespaces=2%2C8&title=.*%5C.js

I started de-duplicating gadgets (ignoring user scripts for now) and I see the following people may have insight into gadget needs based on gadgets that might be manipulating the HTML of section headings so I would be curious for what requirements they'd have for an API that needs access to sections:
@DannyS712 @MusikAnimal @Nux @AlexisJazz

This is very interesting. Yes, I hack your HTML a lot. It's pretty maintenance-intensive. https://en.wikipedia.org/wiki/User:Alexis_Jazz/Factotum adds multiple buttons/links. (configurable, but it can add like six or seven max I think) Especially because I aim to support all skins, including Minerva.

Some quick thoughts:

• The obvious: specify:
  • label/link name
  • .classes
  • #id
  • event(s)
  • which section(s) to add the link/button to
• Easy access (html data attribute?) to:
  • Section title in plain text.
  • Anchor for section.
  • Actual wikitext for section title. This would be GREAT because right now I do something like this:
    • Get innerText section title from HTML.
    • Get wikitext.
    • Search wikitext for sections (search the Factotum code for (?:^|\n)[=]+, you know how it is)
    • Put it through flattenWikiText(), e.g. FTT.flattenWikiText('==Check this [[link]] it\'s \'\'\'awesome\'\'\'==') => "==Check this link it's awesome=="
    • Compare that to the innerText. It's WAY more complicated but you get the idea here.
    • "Hey AlexisJazz, Y U NO use section number?" Because section numbers can change. Random archiverbot shows up after you loaded the page -> all section numbers invalidated.
  • This is probably a stretch, but if we could have the page title from the page the section is from (in case of transcluded sections), yeah, that would be GREAT.
    • Sorry, not thinking straight, I was thinking of sectionless transclusion which is obviously not something that can be resolved with this. Nevertheless, the page title for the section should be available similar to how you can extract that from the edit section link currently.
• Also consider .firstHeading which is section 0
• Allow adding an empty div with some id/class for maximum flexibility. For example, some gadgets/scripts could wish to add a dropdown instead of a button to a section title. You can't accommodate for such specific needs, so just allow the addition of an empty div that the script could populate itself.

@Schnark may also be interested as I think https://de.wikipedia.org/wiki/Benutzer:Schnark/js/fliegelflagel also did this. @Qwerfjkl may be interested as well.

Also @Jack_who_built_the_house for https://commons.wikimedia.org/w/index.php?title=User:Jack_who_built_the_house/Convenient_Discussions

@AlexisJazz Thanks for subscribing.

I want to talk about placing of the section buttons. Initially, Convenient Discussions added section buttons to the side of headings, inside [ edit ]:

They even had disabled/pending/hidden states.

Later, Vector 2022 emerged with its narrower content area and DiscussionTools with its decorations. This is when I decided to get rid of the section buttons next to "edit" and moved all section actions to the metadata bar which I borrowed from DT. The reasoning for that is that if you have a long enough heading, it will quickly wrap to the next line and look something like this:

DiscussionTools	Convenient Discussions

Probably it's less critical to articles with no "Subscribe" button, shorter headings and smaller font for them (and no metadata bar where you can shift the menu to). But at some point you may find yourself in a situation with buttons occupying the valuable area between the heading and some right-floating image or infobox. Example of an article at 1500px window width:

(Side note / offtopic: given that Vector's sidebar header buttons now look differently, maybe it's time to change the look of section buttons as well, moving away from this [ bracket style ] inspired by text-based UIs?)

Thanks for pinging me. I've also had difficulty modifying section headers for my script CFDLister - I had to draw on my limited JavaScript knowledge to make a dropdown in the section header (https://en.wikipedia.org/wiki/User:Qwerfjkl/scripts/CFDlister.js#L-463).
With a few scripts running together section headers can easily get messy:

Hi. I specifically moved buttons away from section headers recently and into a template we can control locally (on wiki). This has drawbacks -- I needed to add section names to the template... but also again something we can control locally, not something that might change with a skin or MW update.

So this kind of works for our del requests, but is not ideal:

I mostly agree with what AlexisJazz said. I don't think I would need to be able to get wikitext though (I assume getting wikitext would be async, so slow). I would need to be able to get an HTML fragment (e.g as a list of elements inside the section.

So this would definitely not work for me:

 /** HTMLElement|null representing section tag - null in legacy parser */
const element;

If I need to worry about which parser is used then I would prefer not to have this in the interface at all. But, as mentioned above, I would also love to have the Section.elements accessor instead :)

I should mention that what I would actually love to have is <section> or any kind of parent/wrapper of the elements in the section. That would make many such things as nominations easier (del requests, good article, dyk article etc).