Reconsider making MarkdownTableOfContents require a Markdown reference

[davep]

a10d2d9 appears to have introduced a requirement for a Markdown reference to be passed to MarkdownTableOfContents. This is potentially problematic for any application that wants to compose the two widgets in very different parts of the DOM, such that neither of them will have knowledge of the other, and any communication between them is bridged by a parent.

Long story short: because Frogmouth decouples the two widgets and neither has knowledge of the other, instead having the owning screen handle the messages and bridge them across the DOM, the change broke Frogmouth and potentially adds unnecessary complexity to fix (at the moment I'm working around it with a throwaway Markdown instance).

If the new parameter is necessary, could it at least be optional?

[rodrigogiraoserrao]

There's something I don't get, though: isn't a TOC inherently dependent on the document whose contents it's capturing?

[davep]

It could technically display the TOC of one document with two viewers - an extreme case, I grant, but not impossible.

But also I feel this this makes it harder to compose an application where the ToC isn't DOM-adjacent to the document (see Frogmouth for example, where it is used as one of a number of external sources of input to the viewer).

I feel this would be a case where making the document itself at least entirely optional.

[willmcgugan]

This might be alleviated if we had some mechanism to pass messages that doesn't go through the DOM. Some kind of pub-sub system. Not sure what form that would take. Just floating the idea.

[davep]

Good point.

I also forgot to add here (and the above reminds me) that the relationship between ToC and Markdown isn't hierarchical, as most other message-sending things are. Markdown sends a message on new ToC data but the ToC widget isn't higher in the DOM and never captures it directly. It needs a bridging container (see MarkdownViewer).

[rodrigogiraoserrao]

Well, I do agree that something feels off, here...

relationship between ToC and Markdown isn't hierarchical, as most other message-sending things are.

The docs for compound widgets show that messages are also used like this. A child A posts a message to a parent widget P which then uses it to do something on a child B.
So, at least my adding the parameter to enable adding a control property to the message is wrong.
Maybe the overarching issue is that the message shouldn't float from the TOC to the Markdown via the parent "bridge".
To communicate down, the MarkdownViewer should use methods and reactives, right?
At least, that is what the docs suggest.

[davep]

To communicate down, the MarkdownViewer should use methods and reactives, right?

• Markdown has TableOfContentsUpdated, which lets anyone above know that the table of contents have changed.
• MarkdownTableOfContents has a table_of_contents reactive that, when set, reconfigures its display.
• Markdown has TableOfContentsSelected, which is used by MarkdownTableOfContents to let anyone above know that a selection has been made from the table of contents (the provenance of this message is questionable, it likely should be mark of MarkdownTableOfContents and perhaps called Selected, but it works as is).

I think, mostly, this is what we're already looking at. MarkdownViewer uses events to see what Markdown and MarkdownTableOfContents are both up to, and it uses reactives and methods to create an overall working viewer.

Frogmouth does pretty much the same, just with the viewer and the ToC even more separated and with the main screen handling the compound-widget-a-like conversation. The need to explicitly tell the ToC widget what viewer widget it's related to seems like a complication here.

But, like I've suggested above, I can see it potentially being useful as an optional thing to set, for some uses, but having it mandatory would seem to complicate others.

[willmcgugan]

Possibly worth doing. But low priority unless somebody asks for it. Closing for now.

[github-actions]

Don't forget to star the repository!

Follow @textualizeio for Textual updates.