🖲 [Spike] Add button role

[jnywong]

Ref: 2i2c-org/infrastructure#5346

Co-authored-by: Angus Hollands [email protected]

This PR is a spike for a button role. Sphinx-design has button directives, but these feel under-constrained for mystmd. Furthermore, buttons feel like "special links", and links are inline elements. As a consequence, @jnywong and I decided to implement a button as a special kind of link. We also added a class attribute to the Link node. This will enable primary-secondary styling of buttons in future. This is probably the way that we'll go for all node types — add class and maybe label etc. to every node.
With a recent discussion for adding inline-attributes to roles ({button .secondary}`My button <https://>.` ), this might become a nice UX. This may also be relevant if we support inline attribute annotation of Markdown syntax, e.g. {kind=button}[a button](https://...)
To support sphinx-design, we might consider "upgrading" button directives into block-divs containing {button}`...` in future.
-- @agoose77

Related PRs

• Add support for buttons myst-theme#521

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3b0795e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[agoose77]

Buttons feel inherently link-like, i.e. they are not new node types, but more of a styling augmentation.

[rowanc1]

Thanks for the PR (taking a quick look while in draft!). I am curious if there is going to be conceptually more to myst-ext-button package in the future? In which case, maybe expanding the package name to cover it?

[rowanc1]

Nice - this means there is a good fallback.

[jnywong]

Hey @rowanc1 ! Yeah @agoose77 and I were prototyping today and made a lot of pivots!

I am curious if there is going to be conceptually more to myst-ext-button package in the future? In which case, maybe expanding the package name to cover it?

We very quickly found there's a myriad ways authors may want to style links, and initially borrowed some inspiration from the existing card component. For this PR, we're going to be focused on a button package specifically and will hopefully converge on extensibility in a future iteration.

[rowanc1]

Makes sense, forgot about the card package as an analogy.

[choldgraf]

Can you provide short user-facing documentation for how this would be used? That would make it easier to understand the implications of role vs. directive etc.

The most common use-case I can imagine for a button is in situations like this:

Some paragraph with a call to action.

[Click me button]

And some more paragraph text.

It sounds like this implementation would be accomplished with the following, is that right?

Some paragraph with a call to action.

{button}`Some call to action text`

And some more paragraph text.

In the context of landing pages you might see one or more buttons next to each other, e.g.

# Title

![A wide hero-style image]()

[Click me button] [Another button]

In this case, is it correct that accomplishing these would be accomplished with:

# Title

![A wide hero-style image]()

{button}`Button text 1` {button}`Button text 2`

Beyond the case for two buttons side-by-side in a landing page-style site, what usecase do you imagine for the "role-like" functionality? E.g. do you imagine users will be doing things like writing some text and {button}`Click Me` putting an inline button like that?

Finally, just noting that one of the useful features of sphinx-design was that buttons could link to more than just URLs. You could either point to a page / ref / etc, or you could point to a local static file, and it would resolve the links appropriately. I don't think that is critical functionality for an MVP, but just noting it here as we are talking about configuration surface area and what kind of ways we expect people to use the feature

[agoose77]

I can engage on a few of these right now (though I will circle back for a lengthier reply).

Your examples are how we envisaged using a button — that's the benefit of a role vs directive.¹.

E.g. do you imagine users will be doing things like writing some text and {button}Click Me putting an inline button like that?

Yes, in fact that was one of the things I wanted to do for the AGU demo gallery, but couldn't get the styling right with the constraints at the time.

Finally, just noting that one of the useful features of sphinx-design was that buttons could link to more than just URLs.

Yes, this is a useful feature.

We borrowed the label <reference> Sphinx syntax (used in download, for example) to allow separating the label from the URL. Therefore, the following would be the proposed syntax for linking to documents and/or identifiers:

{button}`Click me <#identifier>`
{button}`#identifier`
{button}`Click me <./document.md>`
{button}`./document.md`

To implement this, we also need to extend crossReference with a kind, just like link.

An uncertainty that I have is whether the existence of two nodes that need "button-like" features implies the need to have

{
  "type": "button",
  "children": [
    {
      "type": "link",
      "url": "..."
    }
  ]
}

instead of

{
  "type": "link",
  "kind": "button",
  "url": "..."
}
  

However, I think in the long run I might prefer using annotations e.g.

{kind=button}[Click me](#identifier)
{kind=button}[](#identifier)
{kind=button}[Click me](./document.md)
{kind=button}[](./document.md)

Footnotes

1. For completeness, there's nothing in mystmd that precludes us from having directives produce inline node types. But we tend to consider directives as "block like" rather than "inline like". ↩