Add shortcuts feature to the explainer and spec

[aarongustafson]

This change (choose one):

• Breaks existing normative behavior (please add label "breaking")
• Adds new normative requirements
• Adds new normative recommendations or optional items
• Makes only editorial changes (only changes informative sections, or
  changes normative sections without changing behavior)
• Is a "chore" (metadata, formatting, fixing warnings, etc).

Implementation commitment (delete if not making normative changes):

• Safari (link to issue)
• Chrome (link to issue)
• Firefox
• Edge (public signal)
• Samsung Internet (public signal)

Commit message:

Following discussion on issue #582, adding abbreviated shortcut documentation to the explainer.

---

💥 Error: 500 Internal Server Error 💥

PR Preview failed to build. (Last tried on Nov 4, 2019, 5:58 PM UTC).

More

PR Preview relies on a number of web services to run. There seems to be an issue with the following one:

🚨 Spec Generator - Spec Generator is the web service used to build specs that rely on ReSpec.

🔗 Related URL

�[33m📡 HTTP Error 520:�[39m �[36mhttps://rawcdn.githack.com/aarongustafson/manifest/59eaa7a76963bd58cc39cec549f578efb5f2a9eb/index.html�[39m

If you don't have enough information above to solve the error by yourself (or to understand to which web service the error is related to, if any), please file an issue.

[aarongustafson]

Let me know how this looks @marcoscaceres.

[siusin]

Marked as non substantive for IPR from ash-nazg.

[aarongustafson]

@marcoscaceres @raymeskhoury @kenchris I’ve merged shortcuts into the spec and explainer. I think I’ve managed to catch most of the nuance in the spec-authoring process, but please let me know if I’ve missed anything.

A few notes:

• For clarity, I’ve changed ShortcutInfo to ShortcutItem. I think this makes the spec read a lot better.
• I’ve abstracted the params property of ShortcutItem to a new abstract dictionary RequestParams as it is something that can be reused in many contexts going forward (including Web Share Target).

Thanks for letting me take a crack at this. Hopefully I haven’t broken things too badly. Respec seems generally happy with me right now.

[aarongustafson]

@marcoscaceres I’m trying to figure out why the build is failing, so I tried to run respec-validator locally, but it is failing because respec2html isn’t published. Thoughts?

[kenchris]

cc @mgiuca and @jakearchibald regarding the RequestParams

[mgiuca]

Hi Aaron,

I just saw this! Sorry (I was on leave in June). This is great, I'm glad we're moving ahead on this proposal.

I have some comments and questions but largely this is pretty polished.

[aarongustafson]

The platform conventions for shortcut icons seem to differ quite a bit. For instance, iOS shortcuts use icon masks; Windows jump list entries have colored icons, etc.

Is there a plan on how to deal with this? Should a user agent on IOS create an icon mask from a given image? And/or shouldImageResource’s platform member be evaluated for that scenario?

I feel like that might be a good thing to consider with respect to imageResource in a broader sense. I know some launchers also support different shapes (circle, squircle, etc.)

[NotWoods]

The different launcher shapes are handled by purpose: maskable for image resources right now. Maybe a similar field could be used for ShortcutItems? Depending on the specifics of the platform, another option could be to only use the alpha layer of the shortcut (for iOS, Android) and then use full color elsewhere (Windows).

[aarongustafson]

The different launcher shapes are handled by purpose: maskable for image resources right now. Maybe a similar field could be used for ShortcutItems? Depending on the specifics of the platform, another option could be to only use the alpha layer of the shortcut (for iOS, Android) and then use full color elsewhere (Windows).

Shortcuts piggybacks on ImageResource, so that would be covered.

[mgiuca]

Yeah, since shortcut uses ImageResource, maskable should cover any platform-specific needs with regards to conforming all icons to a specific shape. We don't currently have a solution for platforms that want icons to be all monochrome. It's possible there's a more pressing need for that in relation to shortcuts than generic app icons (since some platforms may have monochrome shortcut icons).

If we want to go down that path, I would propose a new purpose: "monochrome" for ImageResource (that would be separate to this PR). I want to avoid any ability for developers to supply an "iOS icon" and a "Windows icon", etc, because then we will break away from the Web platform's platform neutrality and start seeing apps with poor or no icons on other platforms. (Devs can already technically do this by user-agent-detecting when they serve their manifest, but I want to avoid giving them an explicit feature to do this.)

To do this, we should start a separate issue, starting with an analysis of what shortcut icon guidelines there are on each major platform so we can see whether "monochrome" is necessary and sufficient. Anyone care to do that?

That issue aside, I still think we want to drop params, but happy to be overruled in further discussion. Has there been any more (at TPAC for instance)?

[beverloo]

Would the badge purpose be sufficient? It specifically leaves such flexibility as we have the same constraints in other UI surfaces:

A user agent can present this icon where space constraints and/or color requirements differ from those of the application icon.

[aarongustafson]

Bug filed with WebKit. No commitment yet.

[marcoscaceres]

Filed Firefox bug... seems we can't support this on Android, but doing it on Windows might be an option https://bugzilla.mozilla.org/show_bug.cgi?id=1582341

[hjrchung]

Samsung Internet will also implement this feature.

[mgiuca]

I think the discussion about the platform-specific icon requirements is off-topic of this PR since no matter the outcome of that, we don't need to address it here. Spun off to #795 to continue discussion.

[aarongustafson]

Looping in @slightlyoff for feedback on v1.

[aarongustafson]

@mgiuca Are there any outstanding issues with respect to this PR or are we good to merge?

[mgiuca]

Hi Aaron,

I did a detailed review pass over the PR. Sorry if there are things here that I could have caught earlier but didn't see them.

Mostly these are just detailed nits. Overall this works great.

[mgiuca]

Thanks for the hard work on this @aarongustafson . Just left a few more comments, mostly relating to being clear about normative vs non-normative sentences.

Feel free to merge this after making those changes.