- From: Bo Cupp <notifications@github.com>
- Date: Tue, 29 Jun 2021 18:50:52 -0700
- To: w3c/editing <editing@noreply.github.com>
- Cc: Subscribed <subscribed@noreply.github.com>
- Message-ID: <w3c/editing/pull/309/review/695610091@github.com>
@BoCupp-Microsoft commented on this pull request.
> + , wgURI: "https://www.w3.org/2019/webapps/"
+ , wgPatentURI: "https://www.w3.org/2004/01/pp-impl/114929/status"
+ , edDraftURI: "http://w3c.github.io/editing/docs/virtualKeyboard/"
+ , xref: ["WebIDL"
+ , "DOM"
+ , "HTML"
+ , "geometry"]
+ };
+ </script>
+ <script src='https://www.w3.org/Tools/respec/respec-w3c' class='remove'></script>
+</head>
+
+<body>
+ <section id='abstract'>
+ <p>
+ The {{VirtualKeyboard}} API provides web developers a more granular control of on-screen keyboard (virtual keyboard or VK). The API also provides information about VK geometry, such as rect occlusion and gives ability to opt-out from resizing of the visual viewport in the browser.
nit: grammar issue with "a more granular control"
Suggested new abstract: The {{VirtualKeyboard}} API provides authors with greater control over the visibility of the virtual keyboard (VK), and greater ability to adapt the layout of web pages when VK visibility changes.
> +
+<body>
+ <section id='abstract'>
+ <p>
+ The {{VirtualKeyboard}} API provides web developers a more granular control of on-screen keyboard (virtual keyboard or VK). The API also provides information about VK geometry, such as rect occlusion and gives ability to opt-out from resizing of the visual viewport in the browser.
+ </p>
+ </section>
+ <section id='sotd'>
+ <p>
+ </p>
+ </section>
+ <section>
+ <h2>Introduction</h2>
+ <P>This section is non-normative.</P>
+ <p>
+ The Virtual Keyboard (VK) is the on-screen keyboard used for input in scenarios where a hardware keyboard may not be available. Unlike hardware keyboard, VK can adapt its shape to optimize for the expected type of input.
Suggest cutting this sentence as it doesn't seem relevant to the API: Unlike hardware keyboard, VK can adapt its shape to optimize for the expected type of input.
I think it was useful in the explainer since we were pointing out a gap that inputMode was overloaded to control both shape and visibility and couldn't do both at once, but in the spec I don't see that it's necessary.
> +<body>
+ <section id='abstract'>
+ <p>
+ The {{VirtualKeyboard}} API provides web developers a more granular control of on-screen keyboard (virtual keyboard or VK). The API also provides information about VK geometry, such as rect occlusion and gives ability to opt-out from resizing of the visual viewport in the browser.
+ </p>
+ </section>
+ <section id='sotd'>
+ <p>
+ </p>
+ </section>
+ <section>
+ <h2>Introduction</h2>
+ <P>This section is non-normative.</P>
+ <p>
+ The Virtual Keyboard (VK) is the on-screen keyboard used for input in scenarios where a hardware keyboard may not be available. Unlike hardware keyboard, VK can adapt its shape to optimize for the expected type of input.
+ In addition, user agents respond to the presence of the VK, without any exposure of this information to web developers. This document proposes a new web API surface for VK that developers can use to enable better customization of their webpage's content and experiences.
I think it would be useful in this paragraph to expand on how user agents currently respond to the presence of the VK and what alternatives this API offers. As is I don't think it adds anything compared to the abstract.
Maybe: User agents respond to the presence of the VK by:
1. Repositioning the user agent above the VK
2. Reducing the size of the layout viewport so the VK doesn't occlude it
3. Reducing the size of the visual viewport and padding the layout viewport to ensure it can be shifted above the VK
This API provides a fourth option that allows the user agent to leave its layout and visual viewports unchanged and instead provide information about the intersection of the VK and layout viewport so that the author can adapt the layout of their web pages using JavaScript or CSS environment variables.
It would be good to have graphics illustrating the difference between these behaviors.
> + Conformance requirements phrased as algorithms or specific steps may be
+ implemented in any manner, so long as the end result is equivalent. (In
+ particular, the algorithms defined in this specification are intended
+ to be easy to follow, and not intended to be performant.)
+ </p>
+ </section>
+ <section data-dfn-for="VirtualKeyboard">
+ <h2>The <dfn>VirtualKeyboard</dfn> Interface</h2>
+ <pre class="idl">
+ partial interface Navigator {
+ [SameObject] readonly attribute VirtualKeyboard virtualKeyboard;
+ };
+
+ [Exposed=Window]
+ interface VirtualKeyboard : EventTarget {
+ undefined show();
I think this should be `void` instead of `undefined`.
https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/modules/virtualkeyboard/virtual_keyboard.idl;l=1?q=virtual_keyboard.idl&sq=&ss=chromium
> + attribute EventHandler ongeometrychange;
+ };
+ </pre>
+ <dl>
+ <dt>
+ <dfn>show()</dfn> method
+ </dt>
+ <dd>
+ <p>
+ The method must follow these steps:
+ </p>
+ <ol>
+ <li>If the browsing context's <a href="https://html.spec.whatwg.org/multipage/browsers.html#active-window">active window</a> does not have <a href="https://html.spec.whatwg.org/multipage/interaction.html#sticky-activation">sticky user activation</a>, abort these steps.
+ </li>
+ <li>
+ If the focused element's <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-contenteditable">contenteditable</a> value is false, then abort these steps.
I don't think this is meant to be limited to contenteditable. It should say something like: If the focused (is focused the right word) element is not editable...
We want to include textareas, text-like inputs, and any inputs into which the user can type (in the near future EditContext associated elements too).
> + <dl>
+ <dt>
+ <dfn>show()</dfn> method
+ </dt>
+ <dd>
+ <p>
+ The method must follow these steps:
+ </p>
+ <ol>
+ <li>If the browsing context's <a href="https://html.spec.whatwg.org/multipage/browsers.html#active-window">active window</a> does not have <a href="https://html.spec.whatwg.org/multipage/interaction.html#sticky-activation">sticky user activation</a>, abort these steps.
+ </li>
+ <li>
+ If the focused element's <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-contenteditable">contenteditable</a> value is false, then abort these steps.
+ </li>
+ <li>
+ If the <code>virtualKeyboardPolicy</code> is not <code></code>manual</code> or <a href="https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute">inputMode</a> attribute value is <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode-keyword-none">none</a> then abort these steps.
nit: "inputMode</a> attribute value" should be inputMode</a>'s attribute value
> + </dt>
+ <dd>
+ <p>
+ The method must follow these steps:
+ </p>
+ <ol>
+ <li>If the browsing context's <a href="https://html.spec.whatwg.org/multipage/browsers.html#active-window">active window</a> does not have <a href="https://html.spec.whatwg.org/multipage/interaction.html#sticky-activation">sticky user activation</a>, abort these steps.
+ </li>
+ <li>
+ If the focused element's <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-contenteditable">contenteditable</a> value is false, then abort these steps.
+ </li>
+ <li>
+ If the <code>virtualKeyboardPolicy</code> is not <code></code>manual</code> or <a href="https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute">inputMode</a> attribute value is <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode-keyword-none">none</a> then abort these steps.
+ </li>
+ <li>
+ Call the system API to show the VK.
I think there should be a note somewhere near here that says additional OS heuristics may prevent the VK from being shown. Maybe the "Call the system API to show the VK." should instead say something like "Request that the OS show the VK."
> + <ol>
+ <li>If the browsing context's <a href="https://html.spec.whatwg.org/multipage/browsers.html#active-window">active window</a> does not have <a href="https://html.spec.whatwg.org/multipage/interaction.html#sticky-activation">sticky user activation</a>, abort these steps.
+ </li>
+ <li>
+ If the focused element's <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-contenteditable">contenteditable</a> value is false, then abort these steps.
+ </li>
+ <li>
+ If the <code>virtualKeyboardPolicy</code> is not <code></code>manual</code> or <a href="https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute">inputMode</a> attribute value is <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode-keyword-none">none</a> then abort these steps.
+ </li>
+ <li>
+ Call the system API to show the VK.
+ </li>
+ <li>
+ When the VK is shown by the system, {{VirtualKeyboard/ongeometrychange()}} event is fired that contains the intersection of the keyboard geometry and layout viewport in client coordinates.
+ </li>
+ </ol>
I think you could not have this bullet here. I think it should be covered below when you define when the `geometrychange` event fires.
> + <li>
+ If the focused element's <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-contenteditable">contenteditable</a> value is false, then abort these steps.
+ </li>
+ <li>
+ If the <code>virtualKeyboardPolicy</code> is not <code></code>manual</code> or <a href="https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute">inputMode</a> attribute value is <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode-keyword-none">none</a> then abort these steps.
+ </li>
+ <li>
+ Call the system API to show the VK.
+ </li>
+ <li>
+ When the VK is shown by the system, {{VirtualKeyboard/ongeometrychange()}} event is fired that contains the intersection of the keyboard geometry and layout viewport in client coordinates.
+ </li>
+ </ol>
+ </dd>
+ <dt>
+ <dfn>hide()</dfn> method
most comments above for `show()` also apply to the steps below for `hide()`
> + <li>
+ If the focused element's <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-contenteditable">contenteditable</a> value is false, then abort these steps.
+ </li>
+ <li>
+ If the focused element's <code>virtualKeyboardPolicy</code> is not <code>manual</code> or <a href="https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute">inputMode</a> attribute value is <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode-keyword-none">none</a> then abort these steps.
+ </li>
+ <li>
+ Call the system API to hide the VK.
+ </li>
+ <li>
+ When the VK is hidden by the system, {{VirtualKeyboard/ongeometrychange()}} event is fired that contains the intersection of the keyboard geometry and layout viewport in client coordinates.
+ </li>
+ </ol>
+ </dd>
+ <p class="note">
+ Platform heuristics may impose additional restrictions on VK {{VirtualKeyboard/show()}} and {{VirtualKeyboard/hide()}}. e.g., On Windows the pointer type has to be
nit: On should not be capitalized
> + If the focused element's <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-contenteditable">contenteditable</a> value is false, then abort these steps.
+ </li>
+ <li>
+ If the focused element's <code>virtualKeyboardPolicy</code> is not <code>manual</code> or <a href="https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute">inputMode</a> attribute value is <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode-keyword-none">none</a> then abort these steps.
+ </li>
+ <li>
+ Call the system API to hide the VK.
+ </li>
+ <li>
+ When the VK is hidden by the system, {{VirtualKeyboard/ongeometrychange()}} event is fired that contains the intersection of the keyboard geometry and layout viewport in client coordinates.
+ </li>
+ </ol>
+ </dd>
+ <p class="note">
+ Platform heuristics may impose additional restrictions on VK {{VirtualKeyboard/show()}} and {{VirtualKeyboard/hide()}}. e.g., On Windows the pointer type has to be
+ touch or pen.
nit: other paragraphs don't have hard line breaks dividing their content... remove this one?
> + If the focused element's <code>virtualKeyboardPolicy</code> is not <code>manual</code> or <a href="https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute">inputMode</a> attribute value is <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode-keyword-none">none</a> then abort these steps.
+ </li>
+ <li>
+ Call the system API to hide the VK.
+ </li>
+ <li>
+ When the VK is hidden by the system, {{VirtualKeyboard/ongeometrychange()}} event is fired that contains the intersection of the keyboard geometry and layout viewport in client coordinates.
+ </li>
+ </ol>
+ </dd>
+ <p class="note">
+ Platform heuristics may impose additional restrictions on VK {{VirtualKeyboard/show()}} and {{VirtualKeyboard/hide()}}. e.g., On Windows the pointer type has to be
+ touch or pen.
+ </p>
+ <p class="note">
+ A few people have expressed concerns around {{VirtualKeyboard/show()}} and {{VirtualKeyboard/hide()}} methods not being promise-based. However, we could not find any real use cases around needing promises in this type of operation.
Can you link to an issue?
> + </li>
+ </ol>
+ </dd>
+ <p class="note">
+ Platform heuristics may impose additional restrictions on VK {{VirtualKeyboard/show()}} and {{VirtualKeyboard/hide()}}. e.g., On Windows the pointer type has to be
+ touch or pen.
+ </p>
+ <p class="note">
+ A few people have expressed concerns around {{VirtualKeyboard/show()}} and {{VirtualKeyboard/hide()}} methods not being promise-based. However, we could not find any real use cases around needing promises in this type of operation.
+ </p>
+ <dt>
+ <dfn>overlaysContent</dfn>
+ </dt>
+ <dd>
+ <p>
+ To set the attribute to opt-out of resizing the visual viewport,
Can you say something slightly stronger here: a user agent MUST NOT resize its layout viewport or visual viewport when overlaysContent is true?
Also, I think only top-level browsing contexts are allowed to set this, right? This would probably be the place to mention requirements like that. I think there are other requirements too (secure origin maybe)?
> + }
+ }
+ </style>
+ <div class="map">...</div>
+ <input class="search-box" type="search" placeholder="search...">
+ <div class="locations-list">...</div>
+ <script type="module">
+ navigator.virtualKeyboard.overlaysContent = true
+ </script>
+ </xmp>
+ </pre>
+ </aside>
+ </section>
+ </section>
+ <section>
+ <h2>Privacy and Security Considerations</h2>
Several pieces of information in this section seem like a set of claims that this API doesn't come with significant risk to privacy or security. I don't think we need to cover that. I expected this section to enumerate important implementation details that UAs may or must follow to ensure a secure and privacy preserving implementation. Additionally, I think it would be appropriate to enumerate the responsibilities of authors, if any, to ensure they don't create privacy or security issues when using the API.
Maybe [IndexedDB](https://www.w3.org/TR/IndexedDB-2/#privacy) is a good example.
> + <tr>
+ <td><dfn>keyboard-inset-width</dfn>
+ <td><a href="https://drafts.csswg.org/css-values-3/#length-valuehttps://drafts.csswg.org/css-values-3/#length-value"> length</a>
+ <tr>
+ <td><dfn>keyboard-inset-height</dfn>
+ <td><a href="https://drafts.csswg.org/css-values-3/#length-valuehttps://drafts.csswg.org/css-values-3/#length-value"> length</a>
+ </table>
+
+ <p>The keyboard insets are six <a href="https://drafts.csswg.org/css-env-1/#environment">environment variables</a> that define a rectangle by
+ its top, right, bottom, and left insets from the edge of the viewport. Default value of the keyboard insets are "0px" if a fallback value is not provided else it gets updated when {{VirtualKeyboard/boundingRect}} value changes.
+ The width & height insets are calculated from the remaining insets for developer ergonomics.
+ </p>
+ </section>
+ </section>
+ <section>
+ <h2>Examples</h2>
I think there were [good images in the explainer](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/VirtualKeyboardAPI/explainer.md#examples) to go with these examples. Can you include them to help illustrate the impact of the code?
--
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/editing/pull/309#pullrequestreview-695610091
Received on Wednesday, 30 June 2021 01:51:06 UTC