docs: add accessibility overview

docs/accessibility.md

Index: docs/accessibility.md
diff --git a/docs/accessibility.md b/docs/accessibility.md
new file mode 100644
index 0000000000000000000000000000000000000000..179cee682ea94606759e9347d0c09b40c897e11b
--- /dev/null
+++ b/docs/accessibility.md
@@ -0,0 +1,112 @@
+# Accessibility Overview

[dmazzoni, 2016/09/30 19:34:46]

Thanks for writing this.

Can you please link to this from
https://www.chromium.org/developers/design-documents/accessibility?

It doesn't seem redundant with any existing docs but we should cross-link

[Elly Fong-Jones, 2016/10/03 11:54:42]

As soon as it's landed, I can update that site to link to it.

+
+This document describes how accessibility is implemented throughout Chromium at
+a high level.
+
+## Concepts
+
+The three central concepts of accessibility are:
+
+1. The *tree*, which models the entire interface as a tree of objects, exposed
+   to screenreaders or other accessibility software;
+2. *Events*, which let accessibility software know that a part of the tree has
+   changed somehow;
+3. *Commands*, which come from accessibility software and ask the interface to

[dmazzoni, 2016/09/30 19:34:46]

I think we call this "actions" most often in the code

It might be good to give examples of each of these

[Elly Fong-Jones, 2016/10/03 11:54:42]

Done.
 
I added some synthetic examples of these things.

+   change.
+
+All three concepts are handled at several layers in Chromium.
+
+## Blink
+
+Blink constructs an accessibility tree (a heirarchy of [WebAXObject]s) from the

[dmazzoni, 2016/09/30 19:34:46]

heirarchy -> hierarchy

[Elly Fong-Jones, 2016/10/03 11:54:42]

I have been making this typo my entire life :(

+page it is rendering. WebAXObject is the public API wrapper around [AXObject],
+which is the core class of Blink's accessibility tree. AXObjects come in two
+kinds: [AXNodeObject], which represents a [Node] in the accessibility tree,

[dmazzoni, 2016/09/30 19:34:46]

Two things are unclear in this description:

1. AXLayoutObject is a subclass of AXNodeObject, so the vast majority of nodes
will be AXLayoutObject

2. There are other subclasses, not just those two.

I think this is the best high-level summary:

1. AXObject is the abstract interface, it has some common code but can't be
instantiated
2. Most AXObjects are AXNodeObjects and wrap a node
3. Most AXNodeObjects are AXLayoutObjects that wrap a layout object AND a node
4. There are a few subclasses of AXLayoutObject for specific elements like
tables
5. The remaining AXObjects are subclasses of AXMockObject for things like a
slider thumb or a menu list popup that need to exist in the accessibility tree
but don't correspond to an actual object elsewhere in Blink

[Elly Fong-Jones, 2016/10/03 11:54:42]

Done.

+and [AXLayoutObject], which represents a [LayoutObject] in the accessibility tree.
+LayoutObjects are more or less Nodes with CSS applied; AXLayoutObject exists

[dmazzoni, 2016/09/30 19:34:46]

LayoutObjects are a lot more than that. There are a lot of passes that happen
after a change to the DOM tree. One of the first is style resolution, but that's
a prerequisite for Layout, but otherwise not related. You can get a DOM node's
style without layout, so Nektarios is wrong about that.

The layout pass takes the DOM and the style resolution and builds or updates the
layout tree, which contains the complete tree of how to layout all of the page
content on the page. It handles things like line wrapping, overflow, etc.

Stages after that include building the layer tree, paint tree, and compositing
tree, etc., which accessibility mostly ignores

One thing to note is that there are some LayoutObjects that don't correspond to
nodes, for example "anonymous blocks" that just wrap and group a bunch of
related inline elements. They're super annoying to deal with

[Elly Fong-Jones, 2016/10/03 11:54:42]

Done.

+primarily because certain kinds of node should only appear in the AXObject tree
+depending on details of their geometry or visibility.
+
+The central class responsible for dealing with accessibility events in Blink is
+[AXObjectCacheImpl], which is responsible for caching the corresponding
+AXObjects for Nodes or LayoutObjects. This class has many methods named
+`handleFoo`, which are called throughout Blink to notify the AXObjectCacheImpl
+that it may need to update its tree. Since this class is already aware of all
+accessibility events in Blink, it is also responsible for relaying accessibility
+events from Blink to the embedding content layer.
+
+## The content layer
+
+The content layer lives on both sides of the renderer/browser split. The content
+layer translates WebAXObjects into [AXContentNodeData], which is a subclass of
+[ui::AXNodeData]. The ui::AXNodeData class and related classes are Chromium's
+cross-platform accessibility tree. The translation is implemented in
+[BlinkAXTreeSource]. This translation happens on the renderer side, so the
+ui::AXNodeData tree now needs to be sent to the browser, which is done by
+sending [AccessibilityHostMsg_EventParams] with the payload being serialized
+delta-updates to the tree, so that changes that happen on the renderer side can
+be reflected on the browser side.
+
+On the browser side, these IPCs are received by [BrowserAccessibilityManager],

[dmazzoni, 2016/09/30 19:34:46]

They're actually received by RenderFrameHostImpl, which owns the BAM -
this is important because on Chrome OS we forward the accessibility
events directly to extension processes like ChromeVox, bypassing BAM
entirely

[Elly Fong-Jones, 2016/10/03 11:54:42]

Done.

+which is responsible for:
+
+1. Combining AXNodeData trees into a tree of [BrowserAccessibility] objects.

[dmazzoni, 2016/09/30 19:34:46]

To clarify a bit, this is handled by AXTree, and BrowserAccessibility wraps each
AXNode in the AXTree for the platform-specific implementation

[Elly Fong-Jones, 2016/10/03 11:54:42]

I think I rewrote this to make more sense.

+   This is important because each page has its own accessibility tree, but each
+   Chromium *window* must have only one accessibility tree, so trees from
+   multiple pages need to be combined (possibly also with trees from Views UI).
+   This is done by [AXTreeCombiner].

[dmazzoni, 2016/09/30 19:34:46]

Actually AXTreeCombiner isn't used for this. Rather, the
BrowserAccessibilityManagers all link to each other and present one big composed
tree.

[Elly Fong-Jones, 2016/10/03 11:54:42]

Done.

+2. Dispatching outgoing accessibility events to the platform's accessibility
+   APIs. This is done in the platform-specific subclasses of
+   BrowserAccessibilityManager, in a method named `NotifyAccessibilityEvent`.
+3. Dispatching incoming accessibility commands to the appropriate recipient, via
+   [BrowserAccessibilityDelegate]. For messages destined for a renderer,
+   [RenderFrameHostImpl], which is a BrowserAccessibilityDelegate, is
+   responsible for sending appropriate `AccessibilityMsg_Foo` IPCs to the
+   renderer, where they will be received by [RenderAccessibilityImpl].
+
+## Views
+
+Views generates a tree of AXPlatformNodes corresponding to the tree of Views.

[dmazzoni, 2016/09/30 19:34:46]

Sort of the other way around, each View creates a NativeViewAccessibility, which
is used as the delegate
for a AXPlatformNode that represents a node in the accessibility tree

[Elly Fong-Jones, 2016/10/03 11:54:42]

Done.

+This is implemented in [NativeViewAccessibility] and is mostly straightforward.

[dmazzoni, 2016/09/30 19:34:46]

The un-straightforward part is how the web tree is grated onto
the views tree

[Elly Fong-Jones, 2016/10/03 11:54:42]

Done.

+
+## WebUI
+
+Since WebUI surfaces have renderer processes as normal, WebUI accessibility goes
+through the blink-to-content-to-platform pipeline described above. Accessibility
+for WebUI is largely implemented in JavaScript in [webui-js]; these classes take
+care of adding ARIA attributes and so on to DOM nodes as needed.
+
+## The chrome layer

[dmazzoni, 2016/09/30 19:34:46]

I'd call this the "Chrome OS" layer, since that's the only place
where we currently use the automation API.

[Elly Fong-Jones, 2016/10/03 11:54:42]

Done.

+
+The accessibility tree is also exposed via the [chrome.automation API], which
+gives extension JavaScript access to the accessibility tree, events, and
+commands. This API is implemented in C++ by [AutomationInternalCustomBindings],
+which is renderer-side code, and in JavaScript by the [automation API]. The API
+is defined by [automation.idl], which must be kept synchronized with
+[ax_enums.idl].
+
+[AccessibilityHostMsg_EventParams]: https://cs.chromium.org/chromium/src/content/common/accessibility_messages.h?sq=package:chromium&l=75
+[AutomationInternalCustomBindings]: https://cs.chromium.org/chromium/src/chrome/renderer/extensions/automation_internal_custom_bindings.h
+[AXContentNodeData]: https://cs.chromium.org/chromium/src/content/common/ax_content_node_data.h
+[AXLayoutObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/modules/accessibility/AXLayoutObject.h
+[AXNodeObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/modules/accessibility/AXNodeObject.h
+[AXObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/modules/accessibility/AXObject.h
+[AXObjectCacheImpl]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/modules/accessibility/AXObjectCacheImpl.h
+[AXTreeCombiner]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_tree_combiner.h
+[AXTreeSerializer]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_tree_serializer.h
+[BlinkAXTreeSource]: https://cs.chromium.org/chromium/src/content/renderer/accessibility/blink_ax_tree_source.h
+[BrowserAccessibility]: https://cs.chromium.org/chromium/src/content/browser/accessibility/browser_accessibility.h
+[BrowserAccessibilityDelegate]: https://cs.chromium.org/chromium/src/content/browser/accessibility/browser_accessibility_manager.h?sq=package:chromium&l=64
+[BrowserAccessibilityManager]: https://cs.chromium.org/chromium/src/content/browser/accessibility/browser_accessibility_manager.h
+[LayoutObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/core/layout/LayoutObject.h
+[NativeViewAccessibility]: https://cs.chromium.org/chromium/src/ui/views/accessibility/native_view_accessibility.h
+[Node]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/core/dom/Node.h
+[RenderAccessibilityImpl]: https://cs.chromium.org/chromium/src/content/renderer/accessibility/render_accessibility_impl.h
+[RenderFrameHostImpl]: https://cs.chromium.org/chromium/src/content/browser/frame_host/render_frame_host_impl.h
+[ui::AXNodeData]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_node_data.h
+[WebAXObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/public/web/WebAXObject.h
+[automation API]: https://cs.chromium.org/chromium/src/chrome/renderer/resources/extensions/automation
+[automation.idl]: https://cs.chromium.org/chromium/src/chrome/common/extensions/api/automation.idl
+[ax_enums.idl]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_enums.idl
+[chrome.automation API]: https://developer.chrome.com/extensions/automation
+[webui-js]: https://cs.chromium.org/chromium/src/ui/webui/resources/js/cr/ui/