Proposal for a declarative web share button type

[adactio]

In the explainer doc for the Web Share API, there is reference to declarative alternatives:
https://github.com/w3c/web-share/blob/master/docs/explainer.md#why-not-make-a-share-uri-scheme-like-mailto-instead-of-a-javascript-api

I think there's general agreement that a declarative solution would be good, but that it could never offer the same level of functionality as a JavaScript API. See, for example, this closed issue:
#2

It's true that a declarative solution probably wouldn't be able to provide the power of a JavaScript API (in particular, a promise that returns whether the share succeeded or not). But I don't think a declarative solution needs to offer the same power as the JavaScript API. If it can meet the most common use cases, it's worth having in addition to the JavaScript API.

An existing example of this is client-side form validation. Declarative solutions like the required attribute and input types are enough for the most common use cases, but if you need more power than that, you can use the Constraint Validation API.

A declarative version of the Web Share API would need to provide the most basic functionality of sharing a URL. For anything more powerful than that (and if you need to know if the share succeeded), there's the JavaScript API.

Here's my proposal: a new type value for the button element:

<button type="share">...</button>

The button element currently accepts three possible values: submit, reset, and button. If you use any other value, the button will behave as submit. So if you currently use button type="share" that's the behaviour you'll see in all browsers.

But if browsers do support a new "share" value, they can hand over to the OS, passing the current value of the page URL (and possibly the value of the title element—the one element in HTML that's mandatory).

That still leaves the issue of feature detection.

You can feature detect for type values on the button element in the same way as you can currently feature detect type values on the input element:

var testButton = document.createElement("button");
testButton.setAttribute("type","share");
if (testButton.type != "share") {
// polyfill
}

Going back to this comment on the original issue on a declarative option:

The main advantage of an imperative API is that you can feature detect whether it's supported at all, and you get a promise telling you whether it succeeded.

Extending the list of types for the button element solves the first issue but not the second. I don't think the second issue (knowing if the share succeeded) is a problem as long as the declarative solution exists alongside the JavaScript API (I believe the early discussions were about having a declarative solution instead of a JavaScript API, rather than as well as).

So if all you want to do is allow the user to share the current URL (and maybe title), you could use button type="share". If you need to do anything more complex than that, or if you need to know if the share succeeds, you'd need to use the exisiting JavaScript API. (Perhaps the action of sharing through a button type="share" could emit an event—but then you'd need to use JavaScript to listen for the event so it somewhat negates the reason for using a declarative version in the first place).

I think that extending the list of possible type values for the button element would be considerably less work than, say, minting a new attribute or element, but if any browser folks know of reasons to avoid adding more button types, I'm all ears.

I've written up my thoughts on my blog:
https://adactio.com/journal/17398

Looking forward to getting your feedback.

(I'm assuming that this is the correct place to file this proposal, rather than the WICG Discourse—if I've misunderstood, please let me know.)

[ewilligers]

This is the correct place.

<button type="share" value="...."> could share

• title - the value of the page’s title element
• text - the element's value attribute, if present
• url - the current URL

[marcoscaceres]

Apart from placing a button in the content, I'm not sure what the proposal offers over what (at least one) browser already provides? For instance, Safari UI already provides a share button by default on every page:

Similarly, sharing is built into mobile browsers like Safari:

[adactio]

Yeah, I was thinking about how the value attribute could potentially be used to pass data to the Operating System on what to share, but I worry that the parsing rules would get complex quite quickly. Like, there'd need to be a way of saying which property you're setting the value for, which gets you into key/value pairs, which are hard to shoehorn into a single attribute value.

@ewilligers Are you suggesting that the value attribute could take keywords like url or title?

<button type="share" value="url">

or

<button type="share" value="title>

How would that work for text? Any value other than url or title? (Or is the suggestion that the value attribute could be used to override a value that the browser would otherwise share by default?)

The more I thought about passing values, the more I thought it was something best left to the JavaScript API.

Conceptually, I'm imagining that browsers could treat the declarative Web Share in much the same way as they treat bookmarking. The title and url of a bookmark aren't directly set by the author (or user) but the browser infers them (from the current URL and the title element).

Another idea for passing values (but I'm not keen on this) is using a good ol-fashioned form:

<form>
<input type="hidden" name="url" value="...">
<input type="hidden" name="title" value="...">
<input type="hidden" name="text" value="...">
<button type="share">Share this</button>
</form>

The advantage would be that you could add some kind of fallback for non-supporting browsers (by using the action attribute of the form element) but it just feels quite heavy-handed if 90% of the time the values for url and title are going to be "this URL" and "this page's title element" respectively.

You could—and I really don't like this idea—shift the declarative mechanism from the type attribute on the button element to the method attribute on the form element:

<form method="share">
<input type="hidden" name="url" value="...">
<input type="hidden" name="title" value="...">
<input type="hidden" name="text" value="...">
<button>Share this</button>
</form>

I hate myself for even mentioning that. Feels like it's undermining the fundamental verbs of the web. I'm going to apologise to Roy Fielding for even thinking it.

In fact, forget I ever mentioned using forms or inputs.

While we're putting all our terrible ideas on the table...

When it comes to the browser figuring out "What is the title value?" or "What is the text value?", it would be possible to harvest what's in the head of the document: link rel="canonical", meta name="twitter:title", etc.

But, like I said, unless browsers are going to do that for bookmarking, I don't think they should do it for declarative Web Share.

[adactio]

@marcoscaceres wrote:

Apart from placing a button in the content, I'm not sure what the proposal offers over what (at least one) browser already provides? For instance, Safari UI already provides a share button by default on every page

But if that's the case, isn't that true for the Web Share API in general?

Or are you saying that the value of the API is in setting the values explicitly?

If so, I'd love it if we could get data on how the API is currently being used in the wild. If it turns out that a significant proportion of uses are sharing the current URL and page title, then there's an argument for having a declarative option for that. But if it turns out that the majority of uses of the Web Share API are to share URLs/title/text, etc. other than the current URL and title, then yes, as you say, existing browser functionality would already be covering the declarative use case.

Any browser folks got some creepily invasive usage data they can share? Sorry, I mean, Any browser folks got some telemetry they can share? 😉

@marcoscaceres It's worth remembering that the browser chrome isn't necessarily visible to the user. In the case of progressive web apps that choose to launch with "standalone" (or "fullscreen") on their web app manifest, there's no user-visible way to share the current URL or page title.

I think that progressive web apps are an important use case for the Web Share API in general, and a declarative option in particular.

[ewilligers]

@ewilligers Are you suggesting that the value attribute could take keywords like url or title?

No, but that is like the suggestion from the blog:

 <button type=”share” value=”title,text”>

My suggestion was that a page at theUrl

<title>theTitle</title>
<button type=”share” value=”theText”>

could share

{
  title: 'theTitle',
  text: 'theText',
  url: theUrl
}

[marcoscaceres]

@adactio wrote:

But if that's the case, isn't that true for the Web Share API in general?

No. The API is specialized... using it to share the same page is kinda pointless. The point of the API is a "Twitter" situation, where you have compartments of content and you want to share something very specific (i.e., where sharing the title and URL of the top level document doesn't make sense).

For example, sharing "https://twitter.com/home" is useless, as it's different for everyone... but:

Or are you saying that the value of the API is in setting the values explicitly?

Yes. It's ideally for having multiple things to share:

Where you then share something specific:

[marcoscaceres]

If so, I'd love it if we could get data on how the API is currently being used in the wild.

See above. That's from Twitter.

@marcoscaceres It's worth remembering that the browser chrome isn't necessarily visible to the user. In the case of progressive web apps that choose to launch with "standalone" (or "fullscreen") on their web app manifest, there's no user-visible way to share the current URL or page title.

As Editor of the Web Manifest spec, I'm well aware :) Why this API can also be used for that.

I think that progressive web apps are an important use case for the Web Share API in general, and a declarative option in particular.

I don't disagree. I just think it's already covered by the API tho. The proposal just adds a declarative complexity to something that is already doable with the the same amount of JS with no significant gain.

[saschanaz]

I guess it could be useful in environment where JS isn't available, while I'm not sure what environments would that be.

[adactio]

@marcoscaceres wrote:

I just think it's already covered by the API tho.

Yes, it is already covered by the API: that's the point. As I said, the idea of the declarative option is not to add anything more (in fact it would be less powerful than the JavaScript option), but rather to provide another avenue with a lower barrier to entry.

The proposal just adds a declarative complexity to something that is already doable with the the same amount of JS with no significant gain.

When you say "declarative complexity", is that from an implementor standpoint? Because the whole idea with offering a declarative solution is to enable authors, not implementors (as per the priority of constituencies).

At a fundamental level, declarative technologies have a lower barrier to entry than imperative technologies. HTML and CSS, for example, are easier to learn than JavaScript (at the expense of power). Offering a (less powerful) declarative version of the web share API would allow authors who aren't JavaScript developers to still use the web share API for at least the most common use case (see the example I mentioned above regarding client-side form validation).

So I guess I'm advocating for a cross between the priority of constituencies and the principle of least power.

[adactio]

@marcoscaceres wrote:

The API is specialized... using it to share the same page is kinda pointless.

Not if you're viewing a page in a progressive web app that is standalone or fullscreen. That's how I'm currently using it in the wild, and I'm pretty sure I'm not the only one. If anything, I would expect to see this scenario come up more and more if and when progressive web apps increase in popularity.

[adactio]

I've written a polyfill for <button type="share">:
https://gist.github.com/adactio/092b11a74eded2701335ba27f94d2484

The documentation is here:
https://adactio.com/journal/17405

This polyfill takes an Inception approach to feature detection. There are three nested levels:

1. This browser supports button type="share". Great! Don’t do anything. Otherwise proceed to level two.
2. This browser supports the JavaScript Web Share API. Use that API to share the current page URL and title. Otherwise proceed to level three.
3. Use a mailto: link to prefill an email with the page title as the subject and the URL in the body. Ya basic!

A reduced test case is here:
https://codepen.io/adactio/pen/rNerbPE

[marcoscaceres]

When you say "declarative complexity", is that from an implementor standpoint? Because the whole idea with offering a declarative solution is to enable authors, not implementors (as per the priority of constituencies).

No, from an authoring perspective. But also from an implementer's perspective too.

At a fundamental level, declarative technologies have a lower barrier to entry than imperative technologies.

That's demonstrably false and a common misconception: See OWL, XForms, SVG, or any XML+namespace spec. Even HTML is poorly understood, but it just happens to have extremely robust error recovery (giving the illusion of it being easy). However, that's not a function of it being "declarative". Having said that, JS itself is "declarative", and can be used in a declarative manner (see, for example, methods on array such as .forEach(), .sort(), .reverse(), .includes(), etc.).

Offering a (less powerful) declarative version of the web share API would allow authors who aren't JavaScript developers to still use the web share API for at least the most common use case (see the example I mentioned above regarding client-side form validation).

Again, this is a false dichotomy: there are "web developers", not "JavaScript developers" and "HTML developers" or others. The JS APIs of the platform as much part of the platform as any HTML components.

Not if you're viewing a page in a progressive web app that is standalone or fullscreen. That's how I'm currently using it in the wild, and I'm pretty sure I'm not the only one. If anything, I would expect to see this scenario come up more and more if and when progressive web apps increase in popularity.

I think that would be the appropriate time to re-evaluate adding something to HTML. However, I remain skeptical this is needed for the reasons I already mentioned:

• Poor analogue of what the API provides.
• Most browsers provide sharing already in their main UI, or in context menus.
• The API is already fairly simple to use.

[adactio]

@marcoscaceres We differ in our opinions. What are the next steps?

[ewilligers]

What are the next steps?

The next step (with any proposed web platform feature) would be to see if there is at least one browser vendor interested in implementing the proposal.

I respect the thought you have put into it, but agree with @marcoscaceres.

[adactio]

The explainer document for the Web Share API states that sharing the URL of the current page is a very common case:

Sharing the page's own URL (a very common case) would require some scripting...

But @marcoscaceres wrote in this issue:

The API is specialized... using it to share the same page is kinda pointless.

The explainer document also does a good job of summarising the advantages of providing a declarative option:

The link can be placed declaratively on the page, with no need for a JavaScript click event handler

But again, this has been contradicted by @marcoscaceres in this issue:

The proposal just adds a declarative complexity to something that is already doable with the the same amount of JS with no significant gain.

@marcoscaceres also stated:

I'm not sure what the proposal offers over what (at least one) browser already provides? For instance, Safari UI already provides a share button by default on every page

Whearas the explainer document already says:

The browser UI may not always be available, e.g., when a web app has been installed as a standalone/fullscreen app.

One option here would be to update the explainer document and retroactively remove the case for a declarative solution and the acknowledgement that sharing the current page is a common use case (and the statement that the browser UI can't be relied upon in the case of progressive web apps).

Is there a general acceptance that the explainer document contains false assertions? Or does anyone feel that it accurately represents the case for a declarative option and the case for sharing the current page?

[adactio]

@marcoscaceres wrote:

Even HTML is poorly understood, but it just happens to have extremely robust error recovery (giving the illusion of it being easy). However, that's not a function of it being "declarative".

That’s true. The error handling model is what gives HTML and CSS their robustness. Not all declarative languages are robust—XML being a good example. XML has a brittle error-handling model by design. HTML and CSS have extremely robust error recovery by design. That's what makes them such great entry-level languages (even if, as you point out, they're actually quite complex).

JavaScript doesn't have the same level of robustness in its error handling as HTML or CSS. This is why, throughout the history of the web, we've seen use cases that could already be solved in JavaScript move into the more robust languages.

Consider the earliest uses of JavaScript: image rollovers and form validation. Because the use cases were common, the barrier to entry was lowered by adding :hover to CSS, and attributes like required to HTML (along with newer input types).

Note that if you want to do more complex rollovers or form validation, you may still need to reach for JavaScript. But the CSS and HTML solutions solve for the common use cases. The declarative solutions are in addition to—not instead of—the programmatic solutions.

Crucially, if you make a single mistake in writing JavaScript, the error handling won't be nearly as robust as making a single mistake in CSS or HTML.

So in summary, yes, I completely agree that the error handling is the reason why a declarative option is desirable. I've been using the word "declarative" as shorthand for "declarative and handles errors robustly".

Instead of saying that a declarative solution is desirable, I should be clearer with my language: a solution with robust error handling is desirable.

Fortunately, HTML has forgiving error handling (it just happens to be declarative). And the type attribute on the button element in particular has very robust error handling: it assumes a value of submit if it doesn't recognise a value.

[Krinkle]

Apart from placing a button in the content, I'm not sure what the proposal offers over what (at least one) browser already provides? For instance, Safari UI already provides a share button by default on every page: […]

Similarly, sharing is built into mobile browsers like Safari:

@marcoscaceres wrote:

The API is specialized... using it to share the same page is kinda pointless.

Not if you're viewing a page in a progressive web app that is standalone or fullscreen. […]

👍 I too encounter this at times in offline/homescreen-supported PWAs where authors forget to put a share button in the interface, perhaps because in the development stage one mainly tests in the browser mode where the address bar etc are all there.

[marcoscaceres]

@adactio, I know I've taken a strong counter position here - but please note I'm not exclusively against what you are proposing (it's a "strong position weakly held" situation to tease out all the angles - why I also raised #2 back in 2016).

However, I don't feel it's the appropriate time to standardize something here: We are still sorting out quite difficult problems just related to URL sharing (e.g., #178), and we are just scratching the surface of the - much scarier - file handling (#108).

I think we should defer here until we've gained more implementation and deployment experience of the API. We need to really understand how people will use (and abuse) the API. Similarly, we need to consider a broad range of solutions based on what people are trying to do... the <button> solution might be nice, but so might other solutions we might see emerge by people using the API (e.g., the half-baked shareable attribute idea I proposed in #2).

What I'm saying is that we should see what people build/use and what share libraries get popular being built on top of the Share API. In web terms, the API has only been out "for a little while" and it's not universally deployed yet. I think we should continue to track how people are using the API, and ultimately see if we can derive a declarative solution from "the cow paths".

[adactio]

@marcoscaceres wrote:

I think we should continue to track how people are using the API, and ultimately see if we can derive a declarative solution from "the cow paths".

Agreed! What's the best way to do that? Is there browser telemetry that could help here? Or can we put the call out somewhere to find out how people are currently using the API?

I've opened an issue asking how people are currently using the Web Share API but most people won't be aware of that issue. It's in a repo where I've written up a more detailed explanation of the proposal for a "share" button type.

[marcoscaceres]

Agreed! What's the best way to do that? Is there browser telemetry that could help here?

The Chrome API usage boards usually contain links to various properties using the API. Here is the one for Web Share:
https://chromestatus.com/metrics/feature/timeline/popularity/1501

It currently doesn't list any properties using it there (that's not indicative of sites not using it! just the data is missing for whatever reason).

Or can we put the call out somewhere to find out how people are currently using the API?

We can; but again, it's premature as the usage remains very low (see link above). We should continue to monitor how sites are using it and yes, do a call out at some point. I'd honestly give this another year or two for the API to stabilize before we should consider doing that tho.

[marcoscaceres]

I've opened an issue asking how people are currently using the Web Share API but most people won't be aware of that issue.

About this... that sounds a lot like incubation. I think it might be more appropriate to pitch this over at the WICG along with the proposal. There we can gather the data, work out the shape of the solution, etc. and then once it's more fully formed, bring it here for standardization.

WDYT?

[simevidas]

FWIW, the proposal can now be submitted directly at https://github.com/WICG/proposals/issues. There is no need to post it on https://discourse.wicg.io/.

[adactio]

Thanks, @simevidas — I’ve submitted the proposal to the WICG repo:

WICG/proposals#11

[marcoscaceres]

Thanks @adactio, I've subscribed over on the WICG. Looking forward to continuing the discussion further there.

[ewilligers]

The Chrome API usage boards usually contain links to various properties using the API. Here is the one for Web Share:
https://chromestatus.com/metrics/feature/timeline/popularity/1501

It currently doesn't list any properties using it there (that's not indicative of sites not using it! just the data is missing for whatever reason).

With files there are four counts:
WebShareSuccessfulContainingFiles
WebShareSuccessfulWithoutFiles
WebShareUnsuccessfulContainingFiles
WebShareUnsuccessfulWithoutFiles

Here, "unsuccessful" means the promise is rejected with no share targets available, or the user deciding not to proceed with the share, or disk full, etc.

If it would be useful, Chromium could add counts
WebShareContainingTitle
WebShareContainingText
WebShareContainingUrl
These could be recorded at the time of the share() call, with no need to track success / failure. Proposed CL

[marcoscaceres]

As far as they are used, seems like worthwhile things to know. At leas we will know what the most popular share type is.

[marcoscaceres]

Closing as there the proposal is at the WICG.