Update navigator.canShare, navigator.share, Web Share API

[hamishwillee]

Further updates to navigator.canShare.

The main reason is that following some digging, I have verified that the message is a bit flawed. Essentially it can return invalid true if it does not understand data. It is however useful for feature detection.
I added a simple example using pseudo code for that, and explained it.

Also removed the non-standard header and experimental flag. IMO it is not to either - though I am testing that in BCD. BCD also has spec update.

Also noted that the value for the data is a "base set". This can be extended. Lots of work to be done in Web Share API doc (still to be created).

[github-actions]

Preview URLs

• https://pr8381.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Navigator/canShare
• https://pr8381.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Navigator/share
• https://pr8381.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Web_Share_API

Flaws

Note! 2 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Web_Share_API
Title: Web Share API
on GitHub
Flaw count: 1

• broken_links:
  • Can't resolve /en-US/docs/Web/API/Web_Share_Target_API

External URLs

URL: /en-US/docs/Web/API/Navigator/canShare
Title: Navigator.canShare()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/API/Navigator/share
Title: Navigator.share()
on GitHub

• https://mdn.github.io/dom-examples/web-share/ (1 time) (Note! This may be a new URL 👀)
• https://wpt.live/web-share/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Web_Share_API
Title: Web Share API
on GitHub

• https://mdn.github.io/dom-examples/web-share/ (1 time) (Note! This may be a new URL 👀)
• https://web.dev/web-share-target/ (1 time) (Note! This may be a new URL 👀)

(this comment was updated 2021-08-31 02:53:55.405504)

[hamishwillee]

@saschanaz

• This attempts to capture some general guidance about what might cause false to be returned.
• Is this a reasonable statement? I know that it is true for files - but is it the intent of the API?
• When you refer to "implementation" in the spec about files perhaps not being shareable, do you mean "the user agent" or the underlying OS to which the share data is being passed?
• The term "hostile share" is used in the spec. I can imagine what it would mean, but does not appear to be defined. Is there one that I am missing?

[saschanaz]

The statement is now changed so I'll only answer the last two ones.

When you refer to "implementation" in the spec about files perhaps not being shareable, do you mean "the user agent" or the underlying OS to which the share data is being passed?

Kinda both, the OS or the user agent not supporting the OS feature properly.

The term "hostile share" is used in the spec. I can imagine what it would mean, but does not appear to be defined. Is there one that I am missing?

That's from w3c/web-share#127 but admittedly it's way too vague. Filed w3c/web-share#217

[hamishwillee]

@saschanaz @jpmedley Thanks for the review - adjusted to address your points. A few specifics:

• Removed the info about dependency on Permission API. There is no web-share permission - just a web share "permission policy" permission.
• Does not talk about future extensions, though it does still mention base set of options.
• I now use the terminology recognized or understood to indicate whether a property is understood by the user agent, known/supported mean further than the user agent knows about them. I thought about "valid" and "invalid" but then we run into the issue that the spec users validate for share data (gets a bit messy).
• I added a clarification of what is likely to return false in Update navigator.canShare, navigator.share, Web Share API #8381 (comment)

In addition, I have added docs for navigator.share() and Web Share API to this too.

[jpmedley]

Please format this like the other API overview pages. Here's an example.

[hamishwillee]

Thanks. I copied the Battery Status API - in retrospect, perhaps not a good choice.

[hamishwillee]

Thanks for review @jpmedley. Since then ...

• I accepted all your suggestions (with some minor qualifications). Github wouldn't let me batch merge them - sorry if you got multiple notifications.
• Updated the top level API landing page to match the 'standard'
• Removed the link to web tests

[jpmedley]

Thanks for your patience.

[hamishwillee]

Thanks for yours @jpmedley - much appreciated.