Chrome 154 install API and <install> element

[chrisdavidmills]

Summary

Chrome/Edge 154 are shipping the experimental Navigator.install() method and <install> element, which provide programmatic/declarative ways of creating in-page PWA install buttons.

See also the ChromeStatus entries:

• https://chromestatus.com/feature/5183481574850560
• https://chromestatus.com/feature/5152834368700416

These contain some useful demo links.

Both are currently behind a pref.

This PR adds a data point for each feature.

Test results and supporting details

Related issues

[github-actions]

Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs).

[captainbrosset]

There's missing attributes and parameters, but I'm guessing this was kept simple on purpose, so we at least have the entry points documented, and the rest can be added later.

[Elchi3]

There is no specification but https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/html/html_install_element.idl?q=hTMLInstallElement%20idl suggests that there is HTMLInstallElement API data to record.

[chrisdavidmills]

There is no specification but https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/html/html_install_element.idl?q=hTMLInstallElement%20idl suggests that there is HTMLInstallElement API data to record.

Good spot, @Elchi3. I've added data for the element interface and also for the associated event object interface.

[chrisdavidmills]

@Elchi3 I've just added the properties from the https://wicg.github.io/PEPC/permission-elements.html#inpagepermissionmixin mixin, as it turns out HTMLInstallElement supports those.

Although it doesn't seem to support the promptaction and promptdismiss events.

I'm not sure about the validationstatuschange event. I'll test that now.

[chrisdavidmills]

@Elchi3 I've just added the properties from the https://wicg.github.io/PEPC/permission-elements.html#inpagepermissionmixin mixin, as it turns out HTMLInstallElement supports those.

Although it doesn't seem to support the promptaction and promptdismiss events.

I'm not sure about the validationstatuschange event. I'll test that now.

Tested; the validationstatuschange event is included, so I've added data for it.

[Elchi3]

Given there is no spec, I've done some digging in Chromium and I believe this is the full IDL snippet:

Details

[RuntimeEnabled=InstallElement, Exposed=Window]
interface HTMLInstallElement : HTMLElement {
  [HTMLConstructor] constructor();

  attribute EventHandler oninstallresult;

  [CEReactions, Reflect, URL] attribute USVString? manifestId;
  [CEReactions, Reflect, URL] attribute USVString? manifest;
};

HTMLInstallElement includes InPagePermissionMixin;

enum InstallResult { "success", "aborted", "invalid_data" };
[
    RuntimeEnabled=InstallElement,
    Exposed=Window
] interface InstallResultEvent : Event {
    constructor(DOMString type, optional InstallResultEventInit eventInitDict = {});
    readonly attribute InstallResult result;
};

enum InPagePermissionMixinBlockerReason {
  // No blocker reason.
  "",

  // Blocker reasons supported by all InPagePermissionMixin users.
  "illegal_subframe", "unsuccesful_registration",
  "recently_attached", "intersection_changed",
  "intersection_out_of_viewport_or_clipped",
  "intersection_occluded_or_distorted", "style_invalid",

  // Blocker reason specific to HTMLPermissionElement.
  "type_invalid",
};

interface mixin InPagePermissionMixin {
  readonly attribute boolean isValid;
  readonly attribute InPagePermissionMixinBlockerReason invalidReason;
  readonly attribute PermissionState initialPermissionStatus;
  readonly attribute PermissionState permissionStatus;

  attribute EventHandler onpromptaction;
  attribute EventHandler onpromptdismiss;
  attribute EventHandler onvalidationstatuschange;
};

dictionary InstallResultEventInit : EventInit {
    InstallResult result;
};

dictionary InstallParams {
  required USVString manifest;
  USVString? manifestId;
};

dictionary WebInstallResult {};

[
  RuntimeEnabled=WebAppInstallation,
  ImplementedAs=NavigatorWebInstall
] partial interface Navigator {
  [CallWith=ScriptState, RaisesException, MeasureAs="WebDXFeature::kNavigatorInstall"] Promise<WebInstallResult> install();
  [CallWith=ScriptState, RaisesException, MeasureAs="WebDXFeature::kNavigatorInstall"] Promise<WebInstallResult> install(InstallParams params);
};

I've then added this non-standard IDL to the OWD collector to see if your pull request adds correct non-standard BCD features. You are missing the following features for which I detect support with the flag enabled:

• api.HTMLInstallElement.promptaction_event
• api.HTMLInstallElement.promptdismiss_event
• api.InstallResultEvent.InstallResultEvent (the event constructor)

Normally we would get all this for free if we have a proper specification but not when it is all hidden in explainers and browser source code :)

[chrisdavidmills]

• api.HTMLInstallElement.promptaction_event
• api.HTMLInstallElement.promptdismiss_event

On testing, it looks like these events are not fired. See also the comment at https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/html/html_install_element.idl;l=17?q=hTMLInstallElement%20idl.

• api.InstallResultEvent.InstallResultEvent (the event constructor)

Ah, I'm a bit confused here. I thought we said we weren't going to record BCD for non-callable constructors? Or are we still recording the data, but just not writing the pages?

[Elchi3]

• api.HTMLInstallElement.promptaction_event
• api.HTMLInstallElement.promptdismiss_event

On testing, it looks like these events are not fired. See also the comment at https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/html/html_install_element.idl;l=17?q=hTMLInstallElement%20idl.

Ah OK, they are exposed (behind the flag), but in this case, lets not add them then.

• api.InstallResultEvent.InstallResultEvent (the event constructor)

Ah, I'm a bit confused here. I thought we said we weren't going to record BCD for non-callable constructors? Or are we still recording the data, but just not writing the pages?

That other conversation was purely about HTML element constructors that exist for subclassing reasons. Here you have an event constructor that looks callable to me. new InstallResultEvent("success") works for me.

[chrisdavidmills]

That other conversation was purely about HTML element constructors that exist for subclassing reasons. Here you have an event constructor that looks callable to me. new InstallResultEvent("success") works for me.

Ack, I have multiple levels of confusion today ;-|

Constructor data added. Thanks for bearing with me.

[Elchi3]

Thanks Chris! LGTM 👍
Hopefully a proper specification will follow.

[LiaHiscock]

Hi folks -- I'm about 5 minutes too late, but FWIW, our explainers should be the current source of truth. Specifically here's the error handling section - https://github.com/WICG/install-element/blob/main/explainer-manifest-url.md#results-errors-and-debuggability.

https://aka.ms/WebInstall and https://aka.ms/IInstallElement.

Feel free to email myself liahiscock@microsoft.com and/or kristinlee@microsoft.com if there's anything else we can clarify going forward!

[chrisdavidmills]

Hi folks -- I'm about 5 minutes too late, but FWIW, our explainers should be the current source of truth. Specifically here's the error handling section - https://github.com/WICG/install-element/blob/main/explainer-manifest-url.md#results-errors-and-debuggability.

https://aka.ms/WebInstall and https://aka.ms/IInstallElement.

Feel free to email myself liahiscock@microsoft.com and/or kristinlee@microsoft.com if there's anything else we can clarify going forward!

Thanks, @LiaHiscock. I think we got it just about right, but we'll definitely hit you up for clarification in the future.

[Elchi3]

@LiaHiscock hey there, thank you! For our tooling, a real spec document would be ideal. Specs usually come with "IDL Index" sections which would have cleared up a lot of our questions here.

Not having a real spec document also blocks w3c/browser-specs#2255 which enables tooling to collect the IDL information automatically.