4 files changed, 131 insertions, 0 deletions
diff --git a/layout/docs/AccessibleCaret.rst b/layout/docs/AccessibleCaret.rst
new file mode 100644
index 0000000000..8644e4327b
--- /dev/null
+++ b/layout/docs/AccessibleCaret.rst
@@ -0,0 +1,80 @@
+***************
+AccessibleCaret
+***************
+
+AccessibleCaret is a pair of raindrop shape handles at both ends of selection
+highlight, or it is a single handle at the blinking caret in a text area. It
+assists the user to change the range of the selection highlight or the position
+of the blinking caret on platforms with touch-event support.
+
+
+Meta Bug
+========
+
+`Bug 1124074 <https://bugzilla.mozilla.org/show_bug.cgi?id=1124074>`__ tracks all the open issues.
+
+
+Gecko implementation details
+============================
+
+Preferences
+-----------
+* ``layout.accessiblecaret.enabled_on_touch`` (Enabled on Firefox with touch-event support since 51.)
+* ``layout.accessiblecaret.enabled`` (Defaults off, but it can be turn on to force enable AccessibleCaret.)
+* ``layout.accessiblecaret.hide_carets_for_mouse_input`` (Defaults on. Turn
+  this on to debug AccessibleCaret on desktop browser with mouse events.)
+
+AccessibleCaretEventHub State Transition Diagram
+------------------------------------------------
+
+This diagram depicts the state transition of the state machine in
+AccessibleCaretEventHub, which handles external events and callbacks.
+
+Note that the diagram omits some callbacks which do not cause a state transition
+such as ``NotifySelectionChanged`` or ``Reflow``.
+
+This table is a mapping of the real events and callback to the actions described
+on the edge of the diagram:
+
++---------------------------------------------------+--------------+
+| Real events or callbacks                          | Actions      |
++===================================================+==============+
+| ``eMouseDown`` or ``eTouchStart``                 | Press        |
++---------------------------------------------------+--------------+
+| ``eMouseMove`` or ``eTouchMove``                  | Move         |
++---------------------------------------------------+--------------+
+| ``eMouseUp`` or ``eTouchEnd`` or ``eTouchCancel`` | Release      |
++---------------------------------------------------+--------------+
+| ``eMouseLongTap``                                 | Long tap     |
++---------------------------------------------------+--------------+
+| ``AsyncPanZoomStarted()``                         | Scroll start |
++---------------------------------------------------+--------------+
+| ``AsyncPanZoomStopped()``                         | Scroll end   |
++---------------------------------------------------+--------------+
+| ``NotifyBlur()``                                  | Blur         |
++---------------------------------------------------+--------------+
+
+.. image:: AccessibleCaretEventHubStates.png
+
+Debug Tips
+----------
+
+* Dump AccessibleCaret log from command line: run ``MOZ_LOG=AccessibleCaret:5 ./mach run``.
+* Dump AccessibleCaret log by using a preference: Open ``about:config`` and add a pref ``logging.AccessibleCaret`` with value ``debug`` or ``verbose`` (case matters).
+* ``AC_LOG()`` is useful to add new logs.
+
+
+Developers
+==========
+
+Current maintainer
+------------------
+
+* Ting-Yu Lin <aethanyc@gmail.com>
+
+Developers Emeritus
+-------------------
+
+* Morris Tseng <mtseng@mozilla.com>
+* Jeremy Chen <jeremychen@mozilla.com>
+* Boris Chiou <boris@mozilla.com>*
diff --git a/layout/docs/AccessibleCaretEventHubStates.dot b/layout/docs/AccessibleCaretEventHubStates.dot
new file mode 100644
index 0000000000..e1af363692
--- /dev/null
+++ b/layout/docs/AccessibleCaretEventHubStates.dot
@@ -0,0 +1,37 @@
+// Steps to generate AccessibleCaretEventHubStates.png
+// 1. Install Graphviz
+// 2. dot -T png -o AccessibleCaretEventHubStates.png AccessibleCaretEventHubStates.dot
+//
+// Note: If the edge has 'constraint=false', it is not used in ranking the
+// nodes. http://www.graphviz.org/doc/info/attrs.html#d:constraint
+
+digraph event_hub_states {
+  node [style=filled];
+  edge [color="gray30", fontcolor="gray20", fontsize=12]
+
+  NoAction [label="NoAction\n(Initial)"color="#96FF2F"];
+  NoAction -> PressCaret [label="Press & on a caret"];
+  NoAction -> PressNoCaret [label="Press & not on a caret"];
+  NoAction -> Scroll [label="Scroll start"];
+
+  PressCaret [color="#84D8FF"];
+  PressCaret -> DragCaret [label="Move & distance is large"];
+  PressCaret -> NoAction [label="Release (synthesizing a tap)"];
+
+  DragCaret [color="#84D8FF"];
+  DragCaret -> DragCaret [label="Move"];
+  DragCaret -> NoAction [label="Release"];
+
+  PressNoCaret [color="#E8C516"];
+  PressNoCaret -> NoAction [label="Move & distance is large or\nRelease or\nBlur"];
+  PressNoCaret -> LongTap [label="Long tap"];
+  PressNoCaret -> Scroll [label="Scroll start", constraint=false];
+
+  LongTap [color="#E8C516"]
+  LongTap -> NoAction [label="Release"];
+  LongTap -> Scroll [label="Scroll start", constraint=false];
+
+  Scroll [color="#FF9022"]
+  Scroll -> NoAction [label="Scroll end"];
+  Scroll -> NoAction [label="Blur"];
+}
diff --git a/layout/docs/AccessibleCaretEventHubStates.png b/layout/docs/AccessibleCaretEventHubStates.png
new file mode 100644
index 0000000000..b3ccc69bd5
--- /dev/null
+++ b/layout/docs/AccessibleCaretEventHubStates.png
diff --git a/layout/docs/index.rst b/layout/docs/index.rst
new file mode 100644
index 0000000000..c866eb39e4
--- /dev/null
+++ b/layout/docs/index.rst
@@ -0,0 +1,14 @@
+Layout & CSS
+============
+
+Here contains design documents for the Gecko's style system and layout engine.
+They live in the mozilla-central repository under layout/docs directory.
+
+`Layout page <https://wiki.mozilla.org/Platform/Layout>`__ on mozilla wiki
+contains general information about layout and the layout team at Mozilla.
+
+.. toctree::
+   :maxdepth: 1
+
+   AccessibleCaret
+