Working Group Decision on ISSUE-131 caret-location-api

The decision follows.  The chairs made an effort to explicitly address
all arguments presented in the Change Proposals on this topic in
addition to arguments posted as objections in the poll.

*** Question before the Working Group ***

There is a basic disagreement in the group on how focus rings, carets
and selections are to be managed.  The result was an issue, two change
proposals, and a straw poll for objections:

http://www.w3.org/html/wg/tracker/issues/131
http://www.w3.org/html/wg/wiki/ChangeProposals/CaretSelection
http://lists.w3.org/Archives/Public/public-html/2011Mar/0521.html
http://www.w3.org/2002/09/wbs/40318/issue-131-objection-poll/results

== Uncontested observations == 

A number of observations were made which are not in dispute:

* "[The 'single API' proposal's] DrawFocusRing is a single API that is
  intended to drive both drawing of a focus ring while providing a
  caret position. Accessibility API services for caret position and
  focus rings are separate APIs as developers don't draw the caret and
  focus ring at the same time."

* "Under [the] Change Proposal [to have a single API for caret and
  focus], there's no way for Web authors to report the bounding box of
  a non-caret selection to the a11y layer, which would be useful for
  screen magnifiers and other a11y tools."

None of these were decisive by themselves.  There were people who
supported both proposals even after taking these facts into
consideration.  The fact that they were acknowledged up front was
appreciated.

== Points in Dispute ==

There are several logically independent differences between the two
proposals, and separate objections were raised based on each of these
differences. The strength of objections on each separate point of
difference is evaluated below.

== Objections regarding a single call or separate calls for caret and focus ring ==

A key point of disagreement was whether there should be a single call
to handle both the caret and the focus ring, as under the "Have a
single API for caret positioning and focus ring support" proposal, or
separate API calls for these purposes, as under the "Modify existing
Canvas 2D API caret and focus ring support proposal".

First, it was noted that focus and caret position are typically
reported to platform accessibility APIs separately, and that authors
do not typically draw the caret and focus ring at the same time; this
was not disputed. What was disputed was the conclusion:

    Consequently, the API for each needs to be separated out.

The counter-argument is that the combo API is easier for authors to use:

    drawFocusRing() brings disparate low-level APIs into one
    high-level API, by combining caret positioning with an API that is
    useful to authors not attempting to use accessibility APIs, namely
    the drawing of focus rings in a manner that follows platform
    conventions.

However, others argued that such an API would be harder for authors to
use, and was therefore less likely to be used correctly:

    Although DrawFocusRing provides for a caret position the user
    agent does not know whether it is supporting a caret position or a
    focus ring. The x, y attributes are required.

Also:

    The existing drawFocusRing has an x,y coordinate that draws
    nothing. It simply provides a pixel position that drives a drives
    a magnifier without actually drawing the caret removing any
    benefit of having merged a caret position and a focus ring. This
    version of focus ring also forces the author to have to draw a
    focus ring when they really want to drive the magnification
    position for the caret. Developers almost never draw a caret and a
    focus ring at the same time. So, this makes even more work for the
    author.

This was found to be a strong objection to the "Have a single API
proposal". While authors may be led to incidentally report a caret
position when drawing a focus ring, the case was made that it is
confusing and complex to call an API that is primarily meant to draw a
focus ring, and carefully arrange to clip out all its drawing, solely
to update caret position.


== Objections regarding API to report the bounds of the caret vs just a point ==

An objection raised to the "Have a single API" proposal was that it
does not offer any way to draw a caret that blinks at the user-chosen
rate; this is important for users that may suffer seizures if exposed
to rapidly flashing content.

    DrawFocusRing, in the current specification, only allows the
    author to provide a point. At large magnification levels (4x-20x)
    a magnifier also needs to use the height and width of the caret,
    to be able to properly center the content in the screen. This was
    verified when speaking with Freedom scientific.

This argument seems plausible, and no counter-argument was offered. It
was not claimed that this is already supported, nor was it argued that
this is not a valid use case. Therefore, this was found to be a strong
objection to the "Have a single API" proposal.


== Objections regarding API to identify a non-caret selection to AT ==

It was pointed out, with no objections, that the "Have a single API"
proposal does not allow a non-caret selection position to be reported
to assistive technologies:

    The existing Canvas 2D API specification provides an API called
    DrawFocusRing() that has incomplete support for screen
    magnification tracking of focus rings, carets, and content
    selection. In speaking with some magnifier vendors they need
    access to the caret or selection position rectangle (constituting
    an edge) as well as the accessibility semantics of the
    corresponding object in the fallback content.

And:

    DrawFocusRing does not address magnifier tracking of user content
    selection in canvas. Canvas authors will want to allow for content
    selection. Some user agents, like Internet Explorer, support caret
    tracking during selection whereas others, like Safari on the Mac,
    treat the selection position as a separate entity.

This seems on the face of it like a worthwhile use case. No
counter-argument was offered. It was not claimed that this is in fact
supported, nor was it argued that this is not a valid use case,
despite appearances. Therefore, this was found to be a strong
objection to the "Have a single API" proposal.


== Objections regarding caret/selection APIs not offering drawing and therefore being incomplete ==

One objection to the "Modify existing Canvas 2D API caret and focus
ring support" was that, while it provides for separate reporting of
the caret or selection position, it does not provide for actually
drawing the caret or selection. This, it is claimed, makes the feature
incomplete, and therefore possibly underused:

    The proposal's handling of carets is incomplete. If we are to
    support caret drawing, we should do so using an API that actually
    supports native caret drawing, e.g. the Windows wide-caret
    feature. As it stands, the feature allows the user to set the
    width of the caret but does not support native caret drawing.

Also:

    Yet under this Change Proposal the caret location API doesn't do
    any drawing, it only reports the location of the caret to the a11y
    layer. So Web authors *have to* draw their own, custom carets,
    without being able to use the system default caret drawing.

With respect to APIs that are solely for accessibility and do not serve
an additional, not-accessibility purpose, It was claimed:

    It's important when designing APIs driven by accessibility needs
    to ensure that authors will use it even if they're not thinking
    about accessibility.

As far as we can discern, no objection was offered to providing the
functionality native-style drawing of the caret or selection. At the
same time, no concrete proposal was put forward that enables this
functionality. And the possibility to add such functionality in the
future remains open. Therefore, this not to be a strong objection.


== Objections regarding custom-drawn focus rings ==

There were mutual objections to each proposal, based on whether it
allows non-system-default drawing of the focus ring.

First, we have some objections to the "Have a single API" proposal:

    DrawFocusRing does not ensure that the focus ring, drawn, allows
    the browser to follow focus ring conventions for the OS platform
    that may also reflect user's preferences. It allows the author to
    execute a separate drawing function that would cause the author to
    draw focus using the standard drawing path but not drive
    magnification when that occurs. Therefore the specification allows
    the author to draw focus without driving magnification.

This objection, however, does not fully make its case. Even under the
"Modify" proposal, it is possible to draw focus without driving
magnification. What is different between the two is that under "Have a
single API", it is possible to drive magnification without drawing
system-default focus (therefore allowing custom focus to be drawn
later). But a non-default focus ring can be drawn in any case simply
using path drawing. Given this, it was not established that the "Have
a single API" proposal would lead to a failure to drive
magnification. Thus, this was found to be a weak objection.

Another, similar objection makes the same weak argument, but adds the
argument that authors are not forced to follow system conventions:

   While the drawFocusRing() attempts to follow platform conventions
   it does not force it to do so. In fact, if the author wants to draw
   their own focus ring the API returns without drawing the focus ring
   and the author can then draw their own without notifying a
   magnifier of the focus ring location. In short the API does even
   fully meet the goal of driving a magnifier.

However, no argument was given as to why authors should be forced to
follow system conventions, if they do not wish to do so. So this too
was a weak objection.

On the opposite side of the argument, several objections were made to
removing the capability to draw custom focus rings, but still report
to assistive technologies:

    The evidence so far is that, when Web authors resort to using
    <canvas> for custom widgets, they do so to have complete control
    over the UI of such widgetry. This Change Proposal, by removing
    the canDrawCustom parameter of the focus ring API, forces authors
    to take the built-in focus drawing if they want to report the
    focus to the accessibility layer. The likely result would be that
    Web authors who want to draw custom focus rings will do so anyway,
    but will no longer be able to report such custom focus to the a11y
    layer, thus reducing the accessibility of widgets built with
    <canvas>.

Similarly:

    This proposal doesn't support having the user agent determine if
    the user prefers system rings vs custom rings. In fact, it makes
    it more likely that authors will never use the API since there is
    basically no benefit to doing so other than accessibility, which
    is rarely a good enough motivator in practice. The alternative
    proposal is designed to encourage use even by authors not looking
    to write accessible pages, as it provides useful subtle benefits
    like automatically determining if the focus ring should be drawn.

This was found to be a strong objection. No one disputes that canvas
is often used for custom looks, and being able to indicate focus even
when doing custom drawing seems like a valid use case. No compelling
argument was presented for why this use case should be rejected and
why support for it should be removed.

In addition, another objection to this aspect of the "Modify existing
Canvas 2D API caret and focus ring support" was that it makes focus
handling and caret selection inconsistent in an undesirable way;
authors cannot go with all native-style drawing or all custom-drawing
but would be forced to use a mix:

    Yet under this Change Proposal the caret location API doesn't do
    any drawing, it only reports the location of the caret to the a11y
    layer. So Web authors *have to* draw their own, custom carets,
    without being able to use the system default caret drawing. The
    focus ring API, however, would do the opposite: as described
    above, the proposed focus ring API lacks the ability of Web
    authors to draw custom focus rings and have them reported to the
    A11Y layer. So this CP introduces an undesirable inconsistency
    between the focus ring API and the caret location API.

This was also found to be a strong objection.

Thus, on balance, there are stronger objections to the "Modify existing
Canvas 2D API caret and focus ring support proposal" on this point.

== Objections based on whether blink rate settings are available ==

One objection to the "Have a single API" proposal was that it does not
offer a way to draw the caret at the user's chosen blink rate, and
that this is necessary because some users may suffer seizures from
rapidly flashing content:

    DrawFocusRing's caret position support does not allow for an
    author to acquire caret blink rate settings that may have been set
    to prevent seizures.

This seems like a valid use case, and no counter-argument was
provided. Therefore we find this to be a strong objection.


== Objections based on whether text baseline should be exposed ==

Another objection to the "Have a single API" proposal was that it does
not offer a way to measure the baseline position for drawn text. It
was claimed that this was useful for drawing selection boxes or focus
rings; the baseline is needed to compute the actual position where the
text is drawn, relative to the coordinate passed to drawText:

    In the situation where we are dealing with text content, it is
    essential that we be able to access the text's baseline in order
    to properly compute the drawing path for a caret, selection
    position, or focus ring. This information is not provided in the
    canvas 2D API specification and requires additional computation.

However, in examining the bug originally proposing this change, we
noted the editor's question "which baseline?". As alluded to by the
editor, in typography there are many possible definitions of
baseline. The Change Proposal does not specify which to use, and does
not mention how the measureText() method is supposed to fill it in, in
the way it does for the "width" attribute of the TextMetric interface.

Therefore, while the use case seems valid, we find that the Change
Proposal does not provide a sufficiently detailed description of the
changes necessary to specify it. This constitutes a strong objection
to this aspect of the "Modify existing Canvas 2D API caret and focus
ring support proposal". This could be rectified by a future,
separately raised proposal that provides sufficient detail.


*** Decision of the Working Group ***

Therefore, the HTML Working Group hereby adopts the "The existing
DrawFocusRing text does not provide any guidance to user agent
manufacturers as to how to use the necessary information to support
accessibility API services." Change Proposal for ISSUE-131, with two
exceptions.

  http://lists.w3.org/Archives/Public/public-html/2011Mar/0682.html

The two exceptions are:

 * The change to remove the canDrawCustom parameter from drawFocusRing
   is not adopted.

 * The change to add baseline to the TextMetric interface is not
   adopted.

Of the Change Proposals before us, this proposal, with the noted
exceptions, has drawn the weaker objections.

In addition, we note that the following remain open as areas for
future improvement:

 * Proposals to add support for caret or selection APIs that combine
   drawing and reporting to assistive technologies can be considered,
   and if there is consensus, may be incorporated in the future.

 * Proposals to add baseline measurement support can be considered if
   sufficient detail is provided.

== Next Steps ==

Bug 11239 is to be REOPENED and marked as WGDecision.

Since the prevailing Change Proposal does call for a spec change, the
editor is hereby directed to make the changes in accordance to the
change proposal.  Once those changes are complete ISSUE-131 is to be
marked as CLOSED.

== Appealing this Decision ==

If anyone strongly disagrees with the content of the decision and would
like to raise a Formal Objection, they may do so at this time. Formal
Objections are reviewed by the Director in consultation with the Team.
Ordinarily, Formal Objections are only reviewed as part of a transition
request.

== Revisiting this Issue ==

This issue can be reopened if new information come up. Examples of
possible relevant new information include:

* Details about user agents, accessibility APIs, and assistive technologies
  that conclusively demonstrate some of the information exposed by the
  prevailing proposal is not needed and would not be used.

* Statistics about API usage by authors that shows combination APIs
  are a preferred solution for these use cases.

In addition, we note two issues not fully resolved by this decision,
as noted in the "Decision of the Working Group" section.

=== Arguments not considered ==

* "I object to this Change Proposal, as it fails to address how to
  assist screen magnification products to support users with low
  vision in using canvas, an identified use-case requirement."

This objection, while potentially compelling, did not provide any
detail or supporting evidence. Thus, it was not possible to evaluate
the strength of this objection.

* Several objections were made based on the identity of the authors of
  the proposals, nature of groups that had endorsed it, or claimed
  expertise of those who gave input.

Objections should generally be based on the contents of proposals, not
claimed credentials wrote, contributed to, or endorsed them. In some
cases, first-hand knowledge of particular products or content is
relevant, but that was not the case in many of the 
objections. Relatedly:

* Several objections asserted that one proposal satisfied the needs of
  implementors of assistive technologies when dealing with canvas,
  while the other did not. In particular, Freedom Scientific and AI
  Squared were cited.

While direct information from implementors can be relevant, in this
case, no details or direct citations were provided, making it
impossible to verify or refute these claims. Thus, they were given no
weight.

* "It also contradicts the HTML WG's design philosophy of Users over
  Authors over Implementers over Code Purity, by focusing only on what
  authors might or might not do (with no proof or indication of the
  verity of that assertion)."

No evidence was provided that user needs were neglected when
considering the needs of authors.

* The existing DrawFocusRing text does not provide any guidance to
  user agent manufacturers as to how to use the necessary information
  to support accessibility API services.

This argument was no substantiated; it was not explained what guidance
is necessary but lacking, or what problem is created by not having it.

Received on Monday, 11 April 2011 22:15:39 UTC