MozillaWiki - User contributions [en]

Modules/Core

2019-02-08T14:37:24Z

Surkov.alexander:

<noinclude>
'''Only module owners may edit this page.'''

They may:

* update any information about their module except the name of the owner
* add or remove sub-modules
* change the owner of a sub-module
* add emeritus owners or peers

Other changes, including changes of module owner or addition/removal of modules, must be agreed with the Module Ownership Module group, probably via a discussion in [https://www.mozilla.org/about/forums/#governance mozilla.governance].
</noinclude>
{{Module
|name=Accessibility
|description=Support for platform accessibility APIs. Accessibility APIs are used by 3rd party software like screen readers, screen magnifiers, and voice dictation software, which need information about document content and UI controls, as well as important events like changes of focus.
|owner=[mailto:jteh@mozilla.com Jamie Teh]
|peers=[mailto:dbolter@mozilla.com David Bolter], [mailto:eitan@monotonous.org Eitan Isaacson], [mailto:jteh@mozilla.com James Teh], [mailto:mzehe@mozilla.com Marco Zehe], [mailto:yzenevich@mozilla.com Yura Zenevich]
|ownersemeritus=[mailto:aaron@moonset.net. Aaron Leventhal], [mailto:surkov.alexander@gmail.com Alexander Surkov]
|peersemeritus=[mailto:tbsaunde+mozbugs@tbsaunde.org Trevor Saunders], [mailto:ginn.chen@oracle.com Ginn Chen], Evan Yan
|group=dev-accessibility
|source_dirs=accessible/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=Animation
|description=Declarative animations: CSS animations, CSS transitions, Web Animations API, and off-main thread animations.
|owner=[mailto:bbirtles@mozilla.com Brian Birtles] (:birtles)
|peers=[mailto:hiro@mozilla.com Hiroyuki Ikezoe] (:hiro), [mailto:mwoodrow@mozilla.com Matt Woodrow] (:mattwoodrow)
|group=dev-tech-layout
|source_dirs=dom/animation; and animation-related and interpolation-related code in layout/style, gfx/layers, servo/components/style and servo/ports/gecko
|components=Core::DOM::Animation, Core::CSS Parsing and Computation (for CSS animations/transitions related bugs)
}}

{{Module
|name=Anti-Tracking
|description=Tracking detection and content-blocking.
|owner=[mailto:amarchesini@Mozilla.com Andrea Marchesini]
|peers=[mailto:dlee@mozilla.com Dimi Lee], [mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:ewright@mozilla.com Erica Wright], [mailto:jhofmann@mozilla.com Johann Hofmann]
|group=dev-platform
|source_dirs=toolkit/components/antitracking/, several files under browser/ and netwerk/url-classifier/
|components=Core::Privacy: Anti-Tracking
}}

{{Module
|name=Browser WebAPI
|description=Web API for rendering apps, browser windows and widgets.
|peers=[mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:fabrice@mozilla.com Fabrice Desré]
|ownersemeritus=[mailto:kchen@mozilla.com Kan-Ru Chen]
|group=dev-webapi
|source_dirs=dom/browser-element/
|url=
|components=Core::DOM
}}

{{Module
|name=Build and Release Tools
|description=Tools related to build and release automation and configuration of release builds.
|owner=[mailto:nthomas@mozilla.com Nick Thomas]
|peers=[mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:coop@mozilla.com Chris Cooper]
|group=release-engineering
|source_dirs=browser/config/mozconfigs/, mobile/android/config/mozconfigs/, xulrunner/config/mozconfigs/, b2g/config/, tools/update-packaging/
|url=https://wiki.mozilla.org/ReleaseEngineering
|components=Release Engineering::*
}}

{{Module
|name=Build Config
|description=The build system for Gecko and several mozilla.org hosted Gecko-based applications.
|owner=[mailto:gps@mozilla.com Gregory Szorc] (:gps)
|peers=[mailto:mh@glandium.org Mike Hommey] (:glandium), [mailto:mshal@mozilla.com Mike Shal] (:mshal), [mailto:ted@mielczarek.org Ted Mielczarek] (:ted), [mailto:cmanchester@mozilla.com Chris Manchester](:chmanchester), [mailto:nfroyd@mozilla.com Nathan Froyd] (:froydnj), [mailto:dmajor@mozilla.com David Major] (:dmajor), [mailto:rgiles@mozilla.com Ralph Giles] (:rillian)
|ownersemeritus=Ted Mielczarek (2008-[https://blog.mozilla.org/ted/2013/03/07/gregory-szorc-is-now-the-build-config-module-owner/ 2013]), Benjamin Smedberg (???-[http://benjamin.smedbergs.us/blog/2008-04-30/more-changing-of-the-guard-ted-mielczarek/ 2008]),
|group=dev-builds
|source_dirs=build/, config/, python/mozbuild, tools/cross-commit, tools/cvs2hg-import.py, tools/cvsmgmt/, tools/elf-dynstr-gc/, tools/trees.pl, browser/config/mozconfigs/, mobile/config/mozconfigs/, xulrunner/config/mozconfigs/
|url=http://www.mozilla.org/build/
|components=Core::Build Config
}}

{{Module
|name=Code Analysis and Debugging Tools
|description=Tools for debugging Mozilla code or for analyzing speed, memory use, and other characteristics of it.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=
|group=dev-performance
|source_dirs=tools/codesighs/, tools/debug/, tools/dreftool/, tools/dumpdeps/, tools/footprint/, tools/jprof/, tools/leaky/, tools/memory/, tools/module-deps/, tools/performance/, tools/post_compile/, tools/preloader/, tools/rb/, tools/reorder/, tools/trace-malloc/, tools/uuiddeps/,
|url=
|components=
}}

{{Module
|name=Content HTTP Headers
|description=HTTP headers related to content, e.g. User-Agent, Content-Type, Accept. (Transport-related headers are the responsibility of the Necko module owner.)
|owner=
|peers=[mailto:lmandel@mozilla.com Lawrence Mandel]
|ownersemeritus=[mailto:gerv@mozilla.org Gervase Markham]
|group=dev-platform
|source_dirs=
|url=https://developer.mozilla.org/en/Gecko_user_agent_string_reference
|components=Core::Networking: HTTP
}}

{{Module
|name=Content Security
|description=Native content-based security features enforced in the ContentSecurityManager, including: Content Security Policy (CSP), Mixed Content Blocker (MCB), Subresource Integrity (SRI), Cross-Origin Resource Sharing (CORS) and top-level data: URI blocking.
|owner=[mailto:ckerschbaumer@mozilla.com Christoph Kerschbaumer]
|peers=[mailto:tvyas@mozilla.com Tanvi Vyas], [mailto:dveditz@mozilla.com Dan Veditz], [mailto:amarchesini@mozilla.com Andrea Marchesini], [mailto:jkt@mozilla.com Jonathan Kingston]
|peersemeritus=[mailto:mozilla@sidstamm.com Sid Stamm], [mailto:jonas@sicking.cc Jonas Sicking], François Marier
|group=dev-security
|source_dirs=dom/security
|components=Core::DOM: Security
}}

{{Module
|name=Cookies and Permissions
|description=
|owner=Monica Chew
|peers=[mailto:josh@joshmatthews.com Josh Matthews], [mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:mconnor@steelgryphon.com Mike Connor], [mailto:dwitte@gmail.com Dan Witte], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sdwilsh@shawnwilsher.com Shawn Wilsher (ping on irc)]
|group=dev-tech-network
|source_dirs=extensions/cookie/, netwerk/cookie/
|url=
|components=Core::Networking: Cookies
}}
{{Module
|name=Cycle Collector
|description=Code to break and collect objects within reference cycles
|owner=[https://mozillians.org/en-US/u/mccr8/ Andrew McCreight]
|peers=Peter Van der Beken, Olli Pettay, David Baron
|source_dirs=xpcom/base/nsCycleCollector.* and some support headers
|components=Core::XPCOM
|group=dev-platform
}}
{{Module
|name=C++/Rust usage, tools, and style
|description=Aspects of C++ use such as language feature usage, standard library versions/usage, compiler/toolchain versions, formatting and naming style, and aspects of Rust use as needs arise
|owner=[mailto:nfroyd@mozilla.com Nathan Froyd] (while Ehsan is away)
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:glandium@mozilla.com Mike Hommey], [mailto:jwalden@mozilla.com Jeff Walden], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|source_dirs=non-third-party C++ and Rust code in the tree
|components=Various components
|group=dev-platform
}}
{{Module
|name=docshell
|description=
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:kyle@nonpolynomial.com Kyle Machulis], [mailto:nika@thelayzells.com Nika Layzell]
|peersemeritus=[mailto:jstenback@gmail.com Johnny Stenback], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:justin.lebar@gmail.com Justin Lebar], [mailto:sawang@mozilla.com Samael Wang]
|group=dev-platform
|source_dirs=docshell/, uriloader/
|url=
|components=Core::Document Navigation
}}

{{Module
|name=Document Object Model
|description=
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:hsivonen@iki.fi Henri Sivonen], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:baku@mozilla.com Andrea Marchesini],
[mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:kyle@nonpolynomial.com Kyle Machulis], [mailto:amccreight@mozilla.com Andrew McCreight], [mailto:nika@thelayzells.com Nika Layzell]
|ownersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|peersemeritus=[mailto:justin.lebar@gmail.com Justin Lebar], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:bent.mozilla@gmail.com Ben Turner], [mailto:mounir@lamouri.fr Mounir Lamouri (still active, but slower to respond than previously)], [mailto:me@kylehuey.com Kyle Huey], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:ben@wanderview.com Ben Kelly]
|group=dev-tech-dom
|source_dirs=dom/*, except directories covered by other modules
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM, Core::DOM: CSS Object Model, Core::DOM: Core & HTML
}}

{{Module
|name=DOM File
|description=DOM Blob, File and FileSystem APIs
|owner=[mailto:amarchesini@Mozilla.com Andrea Marchesini]
|peers=[mailto:olli@pettay.fi Olli Pettay]
|group=dev-platform
|source_dirs=dom/file, dom/filesystem
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: File
}}

{{Module
|name=Event Handling
|description=DOM Events and Event Handling
|owner=[mailto:olli@pettay.fi Olli Pettay], [mailto:masayuki@d-toybox.com Masayuki Nakano]
|peersemeritus=[mailto:sshih@mozilla.com Stone Shih]
|group=dev-platform
|source_dirs=dom/events and event handling related code elsewhere
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: Events, Core::Event Handling
}}

{{Module
|name=Web Workers
|description=
|owner=[mailto:baku@mozilla.com Andrea Marchesini]
|peers=[mailto:mrbkap@mozilla.com Blake Kaplan], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey], [mailto:bkelly@mozilla.com Ben Kelly], [mailto:asuth@mozilla.com Andrew Sutherland], [mailto:ytausky@mozilla.com Yaron Tausky]
|ownersemeritus=[mailto:bent.mozilla@gmail.com Ben Turner]
|group=dev-platform
|source_dirs=dom/workers/
|url=https://developer.mozilla.org/En/Using_web_workers
|components=Core::DOM: Workers
}}

{{Module
|name=IndexedDB
|description=
|owner=[mailto:jvarga@mozilla.com Jan Varga]
|peers=[mailto:btseng@mozilla.com Bevis Tseng], [mailto:bugmail@asutherland.org Andrew Sutherland], [mailto:baku@mozilla.com Andrea Marchesini]
|ownersemeritus=[mailto:bent.mozilla@gmail.com Ben Turner]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey]
|group=dev-platform
|source_dirs=dom/indexedDB/
|url=https://developer.mozilla.org/en/IndexedDB
|components=Core::DOM: IndexedDB
}}

{{Module
|name=Editor
|description=
|owner=[mailto:masayuki@d-toybox.com Masayuki Nakano]
|peers=[mailto:m_kato@ga2.so-net.ne.jp Makoto Kato]
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=editor/
|url=http://www.mozilla.org/editor/
|components=Core::Editor
}}

{{Module
|name=Embedding
|description=Gecko embedding APIs and frameworks
|owner=[mailto:myk@mykzilla.org Myk Melez]
|ownersemeritus=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:bdahl@mozilla.com Brendan Dahl], [mailto:tbsaunde@tbsaunde.org Trevor Saunders]
|peersemeritus=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-platform
|source_dirs=embedding/
|url=
|components=Core::Embedding: APIs
}}

{{Module
|name=Find As You Type
|description=Find As You Type (formerly called Type Ahead Find) is a feature that allows quick web page navigation when you type a succession of characters in the body of the displayed page (not in an edit box of or drop down list). Currently seeks new owner.
|owner=
|peers=
|group=dev-accessibility
|source_dirs=extensions/typeaheadfind/
|url=http://www.mozilla.org/access/type-ahead/
|components=
}}

{{Module
|name=Gecko Profiler
|description=Gecko's built-in profiler
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:nnethercote@mozilla.com Nicholas Nethercote], [mailto:jseward@mozilla.com Julian Seward] (LUL), [mailto:kvijayan@mozilla.com Kannan Vijayan] (JS integration), [mailto:shu@mozilla.com Shu-yu Guo] (JS integration), [mailto:tlee@mozilla.com Thinker Lee] (TaskTracer), [mailto:cyu@mozilla.com Cervantes Yu] (TaskTracer), [mailto:b56girard@gmail.com Benoit Girard].
|group=dev-platform
|source_dirs=tools/profiler/
|url=https://developer.mozilla.org/en-US/docs/Mozilla/Performance/Profiling_with_the_Built-in_Profiler
|components=Core::Gecko Profiler
}}

{{Module
|name=Geolocation
|description=Implementation of the Geolocation W3C Spec, location provider apis, and wifi scanning code.
|owner=[mailto:josh@joshmatthews.net Josh Matthews], [mailto:kchen@mozilla.com Kan-Ru Chen]
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner], Garvan Keeley
|peers=
|group=dev-tech-dom
|source_dirs=dom/geolocation, dom/system/, netwerk/wifi
|url=https://developer.mozilla.org/En/Using_geolocation
|components=Core::Geolocation
}}

{{Module
|name=Global Key Bindings
|description=Global hot keys in Mozilla for the browser, editor, mail-news and widgets. Does not include underlined menu accelerators and the like, as those are part of i18n.
|owner=Aaron Leventhal
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|group=dev-accessibility
|source_dirs=dom/xbl/builtin/
|url=http://www.mozilla.org/projects/ui/accessibility/mozkeyintro.html
|components=Core::Keyboard: Navigation
}}

{{Module
|name=Graphics
|description=Mozilla graphics API
|owner=[mailto:jrmuizel@mozilla.com Jeff Muizelaar](Thebes, QCMS, YCbCr, Cairo/Pixman, Regions, OS X, Other)
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:bas.schouten@live.nl Bas Schouten](Layers, Windows), [mailto:jgilbert@mozilla.com Jeff Gilbert](WebGL, ANGLE), [mailto:mwoodrow@mozilla.com Matt Woodrow](Layers API), [mailto:jfkthame@googlemail.com Jonathan Kew](text/fonts), [mailto:nsilva@mozilla.com Nicolas Silva](MozSurface), [mailto:ncameron@mozilla.com Nick Cameron], [mailto:sikeda@mozilla.com Sotaro Ikeda](B2G), [mailto:jnicol@mozilla.com Jamie Nicol](Android), [mailto:snorp@mozilla.com James Willcox](Android), [mailto:mstange@themasta.com Markus Stange](OS X), [mailto:lsalzman@mozilla.com Lee Salzman](Skia, Canvas2D), [mailto:rhunt@mozilla.com Ryan Hunt](OMTP), [mailto:gwatson@mozilla.com Glenn Watson ](WebRender), [mailto:dmalyshau@mozilla.com Dzmitry Malyshau](WebRender)
|peersemeritus=[mailto:bgirard@mozilla.com Benoit Girard](Compositor, Performance), [mailto:ajuma.bugzilla@alijuma.com Ali Juma], [mailto:george@mozilla.com George Wright](Canvas2D), [mailto:mchang@mozilla.com Mason Chang], [mailto:dvander@mozilla.com David Anderson], [mailto:clord@mozilla.com Christopher Lord], [mailto:jdaggett@mozilla.com John Daggett](text/fonts), [mailto:bjacob@mozilla.com Benoit Jacob](gfx/gl), [mailto:jdrew@mozilla.com Joe Drew], [mailto:vladimir@pobox.com Vladimir Vukicevic]
|group=dev-platform
|source_dirs=gfx/, dom/canvas/
|url=https://wiki.mozilla.org/Platform/GFX https://wiki.mozilla.org/Gecko:Layers https://wiki.mozilla.org/Gecko:2DGraphicsSketch
|components=Core::Graphics, Core::Graphics: Layers, Core::Graphics: Text, Core::Graphics: WebRender, Core::GFX: Color Management, Core::Canvas: 2D, Core::Canvas: WebGL
}}

{{Module
|name=APZ (Graphics submodule)
|description=Asynchronous panning and zooming
|owner=[mailto:kgupta@mozilla.com Kartikaya Gupta]
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:tnikkel@mozilla.com Timothy Nikkel], [mailto:dvander@mozilla.com David Anderson], [mailto:mstange@mozilla.com Markus Stange]
|group=dev-platform
|source=gfx/layers/apz
|url=https://wiki.mozilla.org/Platform/GFX/APZ
|components=Core::Panning and Zooming
}}

{{Module
|name=Moz2D (Graphics submodule)
|description=Platform independent 2D graphics API
|owner=[mailto:bschouten@mozilla.com Bas Schouten]
|peers=[mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:gwright@mozilla.com George Wright], [mailto:jwatt@jwatt.org Jonathan Watt]
|group=dev-platform
|source=gfx/2d
|url=https://wiki.mozilla.org/Platform/GFX/Moz2D
|components=Core::Graphics
}}

{{Module
|name=Legacy HTML Parser
|description=
|owner=[mailto:mrbkap@gmail.com Blake Kaplan]
|peers=[mailto:dbaron@dbaron.org David Baron], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:rbs@maths.uq.edu.au rbs@maths.uq.edu.au]
|peersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|source_dirs=parser/htmlparser
|url=http://www.mozilla.org/newlayout/doc/parser.html
|components=Core::HTML: Parser
}}

{{Module
|name=HAL
|description=Hardware Abstraction Layer
|owner=[https://mozillians.org/u/dhylands/ Dave Hylands]
|peers=[mailto:gsvelto@mozilla.com Gabriele Svelto]
|group=dev-platform
|source_dirs=hal/
|components=Core::Hardware Abstraction Layer (HAL)
}}

{{Module
|name=HTML Parser
|description=The HTML Parser transforms HTML source code into a DOM. It conforms to the HTML specification, and is mostly translated automatically from Java to C++.
|owner=[mailto:hsivonen@iki.fi Henri Sivonen]
|peers=[mailto:wchen@mozilla.com William Chen]
|group=dev-platform
|source_dirs=parser/html
|url=http://about.validator.nu/
|components=Core::HTML: Parser
}}

{{Module
|name=I18N Library
|description=
|owner=[mailto:hsivonen@hsivonen.fi Henri Sivonen (encoding)], [mailto:jfkthame@gmail.com Jonathan Kew (except to encoding)]
|peers=[mailto:VYV03354@nifty.ne.jp Masatoshi Kimura], [mailto:gandalf@aviary.pl Zibi Braniecki], [mailto:m_kato@ga2.so-net.ne.jp Makoto Kato]
|ownersemeritus=[mailto:jshin1987@gmail.com Jungshik Shin], [mailto:smontagu@smontagu.org Simon Montagu]
|group=dev-i18n
|source_dirs=intl/
|url=http://mozilla.org/projects/intl/index.html
|components=Core::Internationalization
}}

{{Module
|name=ImageLib
|description=
|owner=[mailto:tnikkel@gmail.com Timothy Nikkel]
|peers=[mailto:aosmond@mozilla.com Andrew Osmond], [mailto:jmuizelaar@mozilla.com Jeff Muizelaar]
|peersemeritus=[mailto:seth.bugzilla@blackhail.net Seth Fowler], [mailto:netzen@gmail.com Brian Bondy], [mailto:justin.lebar@gmail.com Justin Lebar]
|group=dev-platform
|source_dirs=media/libjpeg/, media/libpng/, image/, modules/zlib/
|url=
|components=Core::ImageLib
}}

{{Module
|name=IPC
|description=Native message-passing between threads and processes
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|ownersemeritus=[mailto:wmccloskey@mozilla.com Bill McCloskey]
|peers=[mailto:jld@mozilla.com Jed Davis], [mailto:nfroyd@mozilla.com Nathan Froyd], [mailto:bkelly@mozilla.com Ben Kelly], [mailto:amccreight@mozilla.com Andrew McCreight]
|peersemeritus=[mailto:danderson@mozilla.com David Anderson], [mailto:kchen@mozilla.com Kan-Ru Chen], [mailto:btseng@mozilla.com Bevis Tseng]
|group=dev-platform
|source_dirs=ipc/glue/, ipc/ipdl/, ipc/chromium/
|url=
|components=Core::IPC}}

{{Module
|name=JavaScript
|description=JavaScript engine (SpiderMonkey)
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:jdemooij@mozilla.com Jan de Mooij], André Bargull, [mailto:tcampbell@mozilla.com Ted Campbell], [mailto:jcoppeard@mozilla.com Jon Coppeard], [mailto:sphink@gmail.com Steve Fink], [mailto:arai.unmht@gmail.com Tooru Fujisawa], [mailto:khyperia@mozilla.com Ashley Hauck], [mailto:evilpies@gmail.com Tom Schuster], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:jwalden@mit.edu Jeff Walden], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:till@tillschneidereit.net Till Schneidereit], [mailto:efaust@mozilla.com Eric Faust], [mailto:nfitzgerald@mozilla.com Nick Fitzgerald], [mailto:nnethercote@mozilla.com Nick Nethercote], [mailto:luke@mozilla.com Luke Wagner], [mailto:sunfish@mozilla.com Dan Gohman], [mailto:bobbyholley@gmail.com Bobby Holley]
|peersemeritus=[mailto:brendan@mozilla.org Brendan Eich], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:nmatsakis@mozilla.com Niko Matsakis], [mailto:ejpbruel@mozilla.com Eddy Bruel], [mailto:danderson@mozilla.com David Anderson], [mailto:igor@mir2.org Igor Bukanov], Andreas Gal
|group=dev-tech-js-engine
|source_dirs=js/src
|url=http://www.mozilla.org/js/spidermonkey,
http://developer.mozilla.org/en/docs/About_JavaScript
|components=Core::JavaScript Engine
}}

{{Module
|name=JavaScript JIT
|description=JavaScript engine's JIT compilers (IonMonkey, Baseline)
|owner=[mailto:jdemooij@mozilla.com Jan de Mooij]
|peers=[mailto:bbouvier@mozilla.com Benjamin Bouvier], [mailto:tcampbell@mozilla.com Ted Campbell], [mailto:mgaudet@mozilla.com Matthew Gaudet], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:nicolas.b.pierron@mozilla.com Nicolas Pierron], [mailto:evilpies@gmail.com Tom Schuster], [mailto:sstangl@mozilla.com Sean Stangl], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:luke@mozilla.com Luke Wagner]
|peersemeritus=[mailto:danderson@mozilla.com David Anderson], [mailto:hv1989@gmail.com Hannes Verschore]
|group=dev-tech-js-engine-internals
|source_dirs=js/src/jit
|url=http://www.mozilla.org/js/spidermonkey
|components=Core::JavaScript Engine: JIT
}}

{{Module
|name=JavaScript Debugger Backend
|description=JavaScript debugging hooks
|owner=[mailto:timeless@mozdev.org Josh 'timeless' Soref]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:rginda@hacksrus.com Rob Ginda]
|group=dev-apps-js-debugger
|source_dirs=js/jsd/
|url=http://www.mozilla.org/js/jsd
|components=Other Applications::Venkman JS Debugger
}}

{{Module
|name=jsat
|description=Javascript screen reader that is used in Android and B2G
|owner=[mailto:eitan@monotonous.org Eitan Isaacson]
|peers=[mailto:yzenevich@mozilla.com Yura Zenevich]
|group=dev-accessibility
|source_dirs=accessible/jsat/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=js-ctypes
|description=A foreign function interface which allows privileged JS code to interact with binary code without using XPCOM/XPConnect.
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:bobbyholley@gmail.com Bobby Holley]
|group=dev-tech-js-engine
|source_dirs=js/src/ctypes/
|url=https://wiki.mozilla.org/JSctypes
|components=Core::js-ctypes
}}

{{Module
|name=js-tests
|description=JavaScript test suite
|owner=[mailto:bclary@bclary.com Bob Clary]
|peers=
|group=dev-tech-js-engine
|source_dirs=js/tests/
|url=http://www.mozilla.org/js/tests/library.html
|components=
}}

{{Module
|name=Layout Engine
|description=rendering tree construction, layout (reflow), etc.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:jfkthame@gmail.com Jonathan Kew], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:matt.woodrow@gmail.com Matt Woodrow], [mailto:xidorn+moz@upsuper.org Xidorn Quan]
|group=dev-tech-layout
|source_dirs=layout/%, layout/base/, layout/build/, layout/doc/, layout/forms/, layout/generic/, layout/html/, layout/printing/, layout/tables/, layout/tools/
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout, Core::Layout: Block and Inline, Core::Layout: Floats, Core::Layout: Form Controls, Core::Layout: HTML Frames, Core::Layout: Images, Core::Layout: Misc Code, Core::Layout: R & A Pos, Core::Layout: Tables, Core::Layout: Text, Core::Print Preview, Core::Printing: Output
}}

{{Module
|name=libjar
|description=The JAR handling code (protocol handler, stream implementation, and zipreader/zipwriter).
|owner=[mailto:mwu@mozilla.com Michael Wu]
|peers=[mailto:aklotz@mozilla.com Aaron Klotz]
|group=dev-platform
|source_dirs=modules/libjar
|url=
|components=
}}

{{Module
|name=MathML
|description=MathML is a low-level specification for describing mathematics which provides a foundation for the inclusion of mathematical expressions in Web pages.
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan]
|group=dev-tech-mathml
|source_dirs=layout/mathml/
|url=http://www.mozilla.org/projects/mathml/
|components=Core::MathML
}}

{{Module
|name=Media Playback
|description=HTML Media APIs, including Media Source Extensions and non-MSE video/audio element playback, and Encrypted Media Extensions. (WebRTC and WebAudio not included).
|owner=[mailto:jyavenard@mozilla.com Jean-Yves Avenard]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:cpearce@mozilla.com Chris Pearce]
|peers=[mailto:kinetik@flim.org Matthew Gregan], [mailto:bvandyk@mozilla.com Bryce Van Dyk], [mailto:jolin@mozilla.com John Lin], [mailto:alwu@mozilla.com Alastor Wu], [mailto:jwwang@mozilla.com JW Wang]
|group=dev-media
|source_dirs=dom/media, media/gmp-clearkey/, media/libcubeb/, media/libnestegg/, media/libogg/, media/libopus/, media/libstagefright/, media/libtheora/, media/libtremor/, media/libvorbis/, media/libvpx/, media/omx-plugin/, media/rlz/
|url=
|components=Core::Audio/Video
}}

{{Module
|name=Media Transport
|description=Pluggable transport for real-time media
|owner=[mailto:ekr@rtfm.com Eric Rescorla]
|peers=[mailto:bcampen@mozilla.com Byron Campen], [mailto:abr@mozilla.com Adam Roach], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|group=dev-media
|source_dirs=media/mtransport
|url=
|components=Core::WebRTC::Networking
}}

{{Module
|name=Memory Allocator
|description=Most things related to memory allocation in Gecko, including jemalloc, replace-malloc, DMD (dark matter detector), logalloc, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:n.nethercote@gmail.com Nicholas Nethercote], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-platform
|source_dirs=memory/
|components=Core::DMD, Core::jemalloc
}}

{{Module
|name=mfbt
|description=mfbt is a collection of headers, macros, data structures, methods, and other functionality available for use and reuse throughout all Mozilla code (including SpiderMonkey and Gecko more broadly).
|owner=[mailto:jwalden@mit.edu Jeff Walden]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd], [mailto:Ms2ger@gmail.com Ms2ger], [mailto:mh+mozilla@glandium.org Mike Hommey]
|group=dev-platform
|source_dirs=mfbt/
|url=
|components=Core::MFBT
}}

{{Module
|name=Mozglue
|description=Glue library containing various low-level functionality, including a dynamic linker for Android, a DLL block list for Windows, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd] (mozglue/linker), [mailto:kgupta@mozilla.com Kartikaya Gupta] (mozglue/android), [mailto:nchen@mozilla.com Jim Chen] (mozglue/android), [mailto:aklotz@mozilla.com Aaron Klotz] (Windows Dll Blocklist/Interceptor)
|group=dev-platform
|source_dirs=mozglue/
|components=Core::mozglue
}}

{{Module
|name=mozilla-toplevel
|description=The top level directory for the mozilla tree.
|owner=[[Modules/Firefox_Technical_Leadership|Firefox Technical Leadership module]]
|ownersemeritus=[mailto:brendan@mozilla.org Brendan Eich]
|peers=
|group=
|source_dirs=tools/README
|url=
|components=
}}

{{Module
|name=MSCOM
|description=Integration with Microsoft Distributed COM
|owner=[mailto:aklotz@mozilla.com Aaron Klotz]
|peers=[mailto:jteh@mozilla.com James Teh], [mailto:jmathies@mozilla.com Jim Mathies]
|group=dev-platform
|source_dirs=ipc/mscom/%
|url=
|components=Core::IPC: MSCOM}}

{{Module
|name=Necko
|description=The Mozilla Networking Library
|owner=[mailto:dd.mozilla@gmail.com Dragana Damjanovic]
|peers= [mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:mnovotny@mozilla.com Michal Novotny], [mailto:hurley@mozilla.com Nick Hurley], [mailto:dd.mozilla@gmail.com Dragana Damjanovic ], [mailto:valentin.gosu@gmail.com Valentin Gosu], [mailto:daniel@haxx.se Daniel Stenberg ], [mailto:jduell.mcbugs@gmail.com Jason Duell]
|ownersemeritus=[mailto:mcmanus@ducksong.com Patrick McManus], [mailto:cbiesinger@gmail.com Christian Biesinger] |peersemeritus= Shih-Chiang Chien, [mailto:bzbarsky@mit.edu Boris Zbarsky], Steve Workman
|group=dev-tech-network
|source_dirs=netwerk/%, netwerk/base/, netwerk/build/, netwerk/cache/, netwerk/dns/, netwerk/locales/, netwerk/mime/, netwerk/protocol/, netwerk/resources/, netwerk/socket/, netwerk/streamconv/, netwerk/system/, netwerk/test/, netwerk/testserver/
|url=http://www.mozilla.org/projects/netlib/, https://developer.mozilla.org/en/Necko
|components=Core::Networking, Core::Networking: Cache, Core::Networking: Cookies, Core::Networking: FTP, Core::Networking: File, Core::Networking: HTTP, Core::Networking: JAR, Core::Networking: Websockets
}}

{{Module
|name=NSPR
|description=Netscape Portable Runtime
|owner=[mailto:kaie@kuix.de Kai Engert]
|peers=[mailto:wtc@google.com Wan-Teh Chang], [mailto:mh@glandium.org Mike Hommey]
|group=dev-tech-nspr
|source_dirs=nsprpub/
|url=http://www.mozilla.org/projects/nspr/
http://www.mozilla.org/projects/nspr/reference/html/
http://www.mozilla.org/projects/nspr/release-notes/
|components=NSPR
}}

{{Module
|name=PDF
|description=Rendering code to display documents encoded in the ISO 32000-1 `PDF' format.
|owner=Chris Jones, Andreas Gal
|peers=[mailto:aadib@mozilla.com Artur Adib], [mailto:bdahl@mozilla.com Brendan Dahl], [mailto:vnicolas@mozilla.com Vivien Nicolas]
|group=dev-platform
|source_dirs=media/pdf/
|url=https://github.com/mozilla/pdf.js
|components=Core::PDF
}}

{{Module
|name=Plugins
|description= NPAPI Plugin support.
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:joshmoz@gmail.com Josh Aas]
|peersemeritus=[mailto:john@pointysoftware.net John Schoenick], [mailto:robert@ocallahan.org Robert O'Callahan], [mailto:jstenback@gmail.com Johnny Stenback], Benjamin Smedberg
|group=
|source_dirs=dom/plugins/, modules/plugin/
|url=https://wiki.mozilla.org/Plugins
|components=Core::Plug-ins
}}

{{Module
|name=Preferences
|description=Preference library
|owner=[mailto:nnethercote@mozilla.com Nicholas Nethercote]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd], [mailto:felipe@mozilla.com Felipe Gomes], [mailto:glandium@mozilla.com Mike Hommey], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-platform
|source_dirs=modules/libpref/
|url=
|components=Core::Preferences: Backend
}}

{{Module
|name=Private Browsing
|description=Implementation of the Private Browsing mode, and the integration of other modules with Private Browsing APIs.
|owner=[mailto:josh@joshmatthews.net Josh Matthews] (while Ehsan is away)
|peers=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=Implementation and consumers of Private Browsing APIs in nsILoadContext, nsIPrivateBrowsingChannel, PrivateBrowsingUtils.jsm and the related glue code.
|url=https://wiki.mozilla.org/Private_Browsing
|components=Firefox::Private Browsing
}}

{{Module
|name=Privilege Manager
|description="caps"
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peersemeritus=[mailto:brendan@mozilla.org Brendan Eich], [mailto:jstenback@gmail.com Johnny Stenback], [mailto:dveditz@mozilla.com Dan Veditz]
|group=dev-tech-dom
|source_dirs=caps/
|url=http://www.mozilla.org/projects/security/components/index.html
|components=Core::Security: CAPS
}}

{{Module
|name=Push Notifications
|description=Push is a way for application developers to send messages to their web applications.
|owners=
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:lina@mozilla.com Lina Cambridge], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:ddamjanovic@mozilla.com Dragana Damjanovic]
|peersemeritus=[mailto:nsm.nikhil@gmail.com Nikhil Marathe]
|group=
|source_dirs=dom/push
|url=
|components=Core::DOM: Push Notifications
}}

{{Module
|name=PyXPCOM
|description=The Python to XPCOM bridge.
|owner=Todd Whiteman
|peers=[mailto:mhammond@skippinet.com.au Mark Hammond]
|group=
|source_dirs=extension/python
|url=https://developer.mozilla.org/en/PyXPCOM
|components=
}}

{{Module
|name=RDF
|description=
|owner=[mailto:axel@pike.org Axel Hecht]
|peers=
|group=dev-tech-rdf
|source_dirs=rdf/
|url=http://www.mozilla.org/rdf/doc/
|components=Core::RDF
}}

{{Module
|name=security
|description=Crypto/PKI code, including NSS (Network Security Services) and JSS (NSS for Java)
|owner=[mailto:rrelyea@redhat.com Bob Relyea], [mailto:martin.thomson@gmail.com Martin Thomson]
|ownersemeritus=[mailto:ttaubert@mozilla.com Tim Taubert]
|peers=[mailto:kaie@kuix.de Kai Engert], [mailto:ryan.sleevi@gmail.com Ryan Sleevi], [mailto:ekr@rtfm.com Eric Rescorla], [mailto:franziskuskiefer@gmail.com Franziskus Kiefer], [mailto:wtc@google.com Wan-Teh Chang], [mailto:dueno@redhat.com Daiki Ueno]
|peersemeritus=[mailto:emaldona@redhat.com Elio Maldonado]
|group=dev-tech-crypto
|source_dirs=dbm/, security/coreconf/, security/dbm/, security/jss/, security/nss/, security/tinderbox/, security/tinderlight/
|url=http://mozilla.org/projects/security/pki/
|components=NSS, JSS, Core::Security, Core::Security: S/MIME
}}

{{Module
|name=Security - Mozilla PSM Glue
|description=Personal Security Manager
|owner=[mailto:dkeeler@mozilla.com Dana Keeler]
|ownersemeritus=[mailto:kaie@kuix.de Kai Engert (2001-2012)]
|peers=[mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:cykesiopka.bmo@gmail.com Cykesiopka], [mailto:jc@mozilla.com J.C. Jones], [mailto:fkiefer@mozilla.com Franziskus Kiefer]
|group=dev-tech-crypto
|source_dirs=security/manager/
|url=
|components=Core::Security: PSM
}}

{{Module
|name=Static analysis & rewriting for C++
|description=Tools for checking C++ code looking for problems at compile time, plus tools for automated rewriting of C++ code.
|owner=[mailto:nika@thelayzells.com Nika Layzell] (while Ehsan is away)
|peers=[mailto:sfink@mozilla.com Steve Fink], [mailto:jrmuizel@mozilla.com Jeff Muizelaar], [mailto:birunthan@mohanathas.com Birunthan Mohanathas], [mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:andi@mozilla.com Andi-Bogdan Postelnicu]
|group=dev-platform
|source_dirs=build/clang-plugin, tools/rewriting among other out of tree tools
|url=
|components=Core::Rewriting & Analysis
}}
{{Module
|name=storage
|description=Storage APIs with a SQLite backend
|owner=[mailto:mak77@bonardo.net Marco Bonardo]
|peers=[mailto:bugmail@asutherland.org Andrew Sutherland], [mailto:jvarga@mozilla.com Jan Varga]
|group=dev-platform
|source_dirs=db/sqlite3/, storage/
|url=http://developer.mozilla.org/en/docs/Storage
|components=Toolkit::Storage, Core::SQL
}}

{{Module
|name=String
|description=
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[https://mozillians.org/en-US/u/froydnj/ Nathan Froyd], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-tech-xpcom
|source_dirs=string/, xpcom/string/
|url=https://developer.mozilla.org/En/Mozilla_internal_string_guide
|components=Core::String
}}

{{Module
|name=Style System
|description=CSS style sheet handling; style data computation
|owner= [mailto:cam@mcc.id.au Cameron McCormack]
|peers=[mailto:dbaron@dbaron.org David Baron], [mailto:emilio@crisal.io Emilio Cobos Álvarez], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:xidorn+moz@upsuper.org Xidorn Quan], [mailto:bzbarsky@mit.edu Boris Zbarsky]
|group=dev-tech-layout
|source_dirs=layout/style/
|url=https://wiki.mozilla.org/Gecko:Overview#Style_System
|components=Core::CSS Parsing and Computation
}}

{{Module
|name=SVG
|description=Scalable Vector Graphics
|owner=[mailto:jwatt@jwatt.org Jonathan Watt]
|peers=[mailto:longsonr@gmail.com Robert Longson], [mailto:robert@ocallahan.org Robert O'Callahan], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:birtles@gmail.com Brian Birtles]
|group=dev-tech-svg
|source_dirs=dom/svg/, layout/svg/, dom/smil/
|url=https://developer.mozilla.org/en-US/docs/Web/SVG
|components=Core::SVG
}}

{{Module
|name=Tamarin
|description=VM for ActionScript and JavaScript
|owner=Edwin Smith, [mailto:jodyer@adobe.com Jeff Dyer]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:stejohns@adobe.com Steven Johnson], [mailto:tierney@adobe.com Erik Tierney], [mailto:treilly@adobe.com Tom Reilly]
|group=dev-tech-js-engine
|source_dirs=js/tamarin
|url=http://www.mozilla.org/projects/tamarin/
http://wiki.mozilla.org/tamarin/
http://hg.mozilla.org/tamarin-central/
http://hg.mozilla.org/tamarin-tracing/
|components=Tamarin
}}

{{Module
|name=Test Harness
|description=In-tree test infrastructure and tools. Harnesses include, XPCShell, Mochitest (& Chrome), Reftest, JsREftest, Compiled Code Tests, Robocop, Mozmill, Marionette, Firefox UI Tests. Requests for new harnesses should go to Testing::General.
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:dbaron@dbaron.org David Baron] (reftest), [mailto:jwalden@mit.edu Jeff Walden] (httpd.js, jsreftest), Rob Campbell (mochitest, mochitest chrome, marionette), [mailto:jmaher@mozilla.com Joel Maher] (reftest, mochitest, jsreftest), [mailto:ctalbert@mozilla.com Clint Talbert] (reftest, compiled code, mozmill), [mailto:geoffbrown@mozilla.com Geoff Brown] (robocop), [mailto:hskupin@mozilla.com Henrik Skupin] (Marionette, Firefox UI tests), [mailto:ato@mozilla.com Andreas Tolfsen] (marionette), [mailto:jgriffin Jonathan Griffin] (marionette), [mailto:dburns@mozilla.com David Burns] (marionette), [mailto:dminor@mozilla.com Dan Minor], [mailto:mjzffr@gmail.com Maja Frydrychowicz] (Marionette, Firefox UI tests), [mailto:james@hoppipolla.co.uk James Graham],

|group=dev-quality
|source_dirs=/testing
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::General, Testing::Mochitest, Testing::Mochitest Chrome, Testing::Marionette, Testing::Mozmill, Testing::Reftest, Testing::XPCShell Harness, Testing::httpd.js
}}

{{Module
|name=Testing Infrastructure
|description=Testing tools and infrastructure for Mozilla projects, harnesses for automated tests, stand-alone test tools. Talos, Graph Server, Mozbase, Pulse, WOO, Bughunter, SUTAgent, Eideticker
|owner=[mailto:jmaher@mozilla.com Joel Maher]
|peers=[mailto:bclary@bclary.com Bob Clary], [mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:ccooper@deadsquid.com Chris Cooper], [mailto:ctalbert@mozilla.com Clint Talbert], [mailto:robert@roberthelmer.com Robert Helmer], [mailto:jmaher@mozilla.com Joel Maher], Rob Campbell, [mailto:wlach@mozilla.com William Lachance], [mailto:jeads@mozilla.com Jonathan Eads], [mailto:jgriffin Jonathan Griffin], [mailto:bmoss@mozilla.com Bob Moss], [mailto:mcote@mozilla.com Mark Côté]
|group=dev-quality
|source_dirs=testing/, tools/httptester/, tools/page-loader/, tools/test-harness/, tools/tests/, tools/testserver/, tools/testy/
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::Infrastructure
}}

{{Module
|name=JS Marionette
|description=NodeJS test harness, marionette client, and other utilities for running marionette tests (submodule of Test Infrastructure)
|owner=[mailto:jlal@mozilla.com James Lal] <lightsofapollo>, [mailto:gaye@mozilla.com Gareth Aye] <gaye>
|peers=[mailto:aus@mozilla.com Ghislain "Aus" Lacroix] <auswerk>
|source_dirs=gaia/tests/jsmarionette
|components=Testing::JSMarionette
|group=dev-gaia
}}

{{Module
|name=XPCShell Test Harness
|description=The XPCShell Harness
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:jmaher@mozilla.com Joel Maher]
|source_dirs=testing/xpcshell
|components=Testing::XPCShell Harness
}}

{{Module
|name=Update Service
|description=server code for Mozilla Update services (aus, addons, pfs)
|owner=Mike Morgan
|peers=[mailto:jscott@mozilla.com Justin Scott], [mailto:shaver@mozilla.org Mike Shaver], [mailto:wclouser@mozilla.com Will Clouser]
|group=dev-amo
|source_dirs=webtools/addons/, webtools/aus/, webtools/update/
|url=http://wiki.mozilla.org/wiki/AMO
|components=AUS::Administration, AUS::Systems
}}

{{Module
|name=View System
|description=The View Manager is responsible for handling "heavyweight" rendering (some clipping, compositing) and event handling tasks.
|owner=[mailto:mstange@themasta.com Markus Stange]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dbaron@dbaron.org David Baron]
|group=dev-tech-layout
|source_dirs=view/
|url=
|components=Core::Layout: View Rendering
}}

{{Module
|name=Web Audio
|description=Support for the W3C Web Audio API specification.
|owner=[mailto:padenot@mozilla.com Paul Adenot]
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:karlt+@karlt.net Karl Tomlinson]
|group=dev-platform
|source_dirs=dom/media/webaudio
|url=https://wiki.mozilla.org/Web_Audio_API
|components=Core::Web Audio
}}

{{Module
|name=Web Painting
|description=painting, display lists, and layer construction
|owner=[mailto:matt.woodrow@gmail.com Matt Woodrow]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:dbaron@dbaron.org David Baron], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:mstange@themasta.com Markus Stange], [mailto:mmynttinen@mozilla.com Miko Mynttinen], [mailto:jnicol@mozilla.com Jamie Nicol]
|group=dev-tech-layout
|source_dirs= layout/painting, the display list and layer related methods on nsIFrame and its subclasses
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout: Web Painting
}}

{{Module
|name=WebRTC
|description=WebRTC is responsible for realtime audio and video communication, as well as related issues like low-level camera and microphone access
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:bcampen@mozilla.com Byron Campen] [mailto:abr@mozilla.com Adam Roach]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=netwerk/sctp (also see submodules "WebRTC Media" and "WebRTC Signaling")
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC, Core::WebRTC Networking
}}

{{Module
|name=WebVR
|description=Gecko's implementation of WebVR (Virtual Reality) functionality, including API, devices, graphics and integration
|owner=[mailto:kgilbert@mozilla.com Kip Gilbert]
|peers=[mailto:dmu@mozilla.com Daosheng Mu]
|peersemeritus=[mailto:vladimir@pobox.com Vladimir Vukicevic]
|group=dev-platform
|source_dirs=dom/vr, gfx/vr
|url=https://mozvr.com/
|components=Core::WebVR
}}

{{Module
|name=Widget
|description=
|owner=[mailto:vladimir@pobox.com Vladimir Vukicevic]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peersemeritus=[mailto:pavlov@pavlov.net Stuart Parmenter],
|group=dev-platform
|source_dirs=widget/, widget/xpwidgets/
|url=
|components=Core::Drag and Drop, Core::Widget, Core::Printing: Setup
}}

{{Module
|name=Widget - Android
|description=The Android Port
|owner=[mailto:blassey.bugs@lassey.us Brad Lassey]
|peers=[mailto:jwillcox@mozilla.com James Willcox]
|group=dev-platforms-mobile
|source_dirs=widget/android/, embedding/android
|url=
|components=Core::Widget: Android
}}

{{Module
|name=Widget - GTK
|description=supported X widgetry and gfx
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|group=dev-platform
|source_dirs=widget/gtk/, widget/gtk2/, widget/gtksuperwin/, widget/gtkxtbin/
|url=http://www.mozilla.org/unix/, http://www.gtk.org, http://www.mozilla.org/ports/gtk/
|components=Core::Widget: Gtk
}}

{{Module
|name=Widget - OS X
|description= Gecko's OS X compatibility layer.
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:spohl@mozilla.com Stephen Pohl], [mailto:joshmoz@gmail.com Josh Aas]
|peersemeritus=[mailto:b56girard@gmail.com Benoit Girard], [mailto:smichaud@pobox.com Steven Michaud]
|group=dev-platform
|source_dirs=widget/cocoa/
|url=
|components=Core::Widget: Cocoa
}}

{{Module
|name=Widget - Windows
|description=Windows widgets and desktop integration
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook], [mailto:vladimir@pobox.com Vladimir Vukicevic], [mailto:jmathies@mozilla.com Jim Mathies]
|peersemeritus=[mailto:blassey@mozilla.com Brad Lassey], [mailto:netzen@gmail.com Brian Bondy], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:doug.turner@gmail.com Doug Turner], [mailto:timeless@mozdev.org Josh 'timeless' Soref], [mailto:robarnold@cmu.edu Rob Arnold]
|group=dev-platform
|source_dirs=widget/windows/
|url=
|components=Core::Widget: Win32
}}

{{Module
|name=XBL
|description=eXtensible Binding Language
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:jonas@sicking.cc Jonas Sicking]
|ownersemeritus=[mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xbl
|source_dirs=dom/xbl/
|url=http://www.mozilla.org/projects/xbl/
|components=Core::XBL
}}

{{Module
|name=XML
|description=XML in Mozilla, including XML, XHTML, Namespaces in XML, Associating Style Sheets with XML Documents, XML Linking and XML Extras. XML-related things that are not covered by more specific projects.
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-tech-xml
|source_dirs=dom/xml/, extensions/xmlextras/, parser/expat/
|url=http://www.mozilla.org/newlayout/xml/
|components=Core::XML
}}

{{Module
|name=XPApps
|description=Cross-Platform Applications, mostly Navigator front end and application shell.
|owner=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|peers=[mailto:dean_tessman@hotmail.com Dean Tessman], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-apps-seamonkey
|source_dirs=xpfe/
|url=http://www.mozilla.org/xpapps/
|components=
}}

{{Module
|name=XPCOM
|description=The cross-platform object model and core data structures.
|owner=[https://mozillians.org/en-US/u/froydnj/ Nathan Froyd]
|peers=[mailto:erahm@mozilla.com Eric Rahm]
|ownersemeritus=Benjamin Smedberg
|peersemeritus=[https://mozillians.org/en-US/u/dougt/ Doug Turner]
|group=dev-platform
|source_dirs=startupcache/, xpcom/%, xpcom/base/, xpcom/build/, xpcom/components/, xpcom/ds/, xpcom/glue/, xpcom/proxy/, xpcom/sample/, xpcom/stub/, xpcom/tests/, xpcom/threads/, xpcom/tools/, xpcom/windbgdlg/
|url=http://developer.mozilla.org/en/XPCOM
|components=Core::XPCOM
}}

{{Module
|name=XPConnect
|description=Deep Magic
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:amccreight@mozilla.com Andrew McCreight], [mailto:kmaglione@mozilla.com Kris Maglione], [mailto:nika@thelayzells.com Nika Layzell]
|peersemeritus=[mailto:gal@uci.edu Andreas Gal], [mailto:jstenback@gmail.com Johnny Stenback], [mailto:gkrizsanits@mozilla.com Gabor Krizsanits]
|group=
|source_dirs=js/xpconnect/
|url=
|components=Core::XPConnect
}}

{{Module
|name=XPIDL
|description=Cross-platform IDL compiler; produces .h C++ header files and .xpt runtime type description files from .idl interface description files.
|owner=[mailto:nika@thelayzells.com Nika Layzell]
|peers=[mailto:nfroyd@mozilla.com Nathan Froyd], [mailto:amccreight@mozilla.com Andrew McCreight]
|ownersemeritus=[mailto:me@kylehuey.com Kyle Huey]
|peersemeritus=[mailto:shaver@mozilla.org Mike Shaver], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-tech-xpcom
|source_dirs=xpcom/typelib/
|url=http://www.mozilla.org/scriptable/xpidl
http://www.mozilla.org/scriptable
|components=
}}

{{Module
|name=XPToolkit
|description=Cross-platform user interface toolkit
|owner=
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:Jan.Varga@gmail.com Jan Varga]
|group=dev-tech-xul
|source_dirs=dom/xul/, layout/xul/
|url=http://www.mozilla.org/xpfe/
|components=Core::XP Toolkit/Widgets: Menus, Core::XP Toolkit/Widgets: XUL
}}

{{Module
|name=XSLT Processor
|description=XSLT transformations processor
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:axel@pike.org Axel Hecht], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xslt
|source_dirs=dom/xslt/
|url=http://www.mozilla.org/projects/xslt/, http://www.w3.org/TR/xslt.html
|components=Core::XSLT
}}

{{Module
|name=Sandboxing - Windows
|description=Sandboxing for the Windows platform
|owner=[mailto:bobowencode@gmail.com Bob Owen] (:bobowen)
|peers=[mailto:aklotz@mozilla.com Aaron Klotz] (:aklotz), [mailto:jimm@mozilla.com Jim Mathies] (:jimm), [mailto:davidp99@gmail.com David Parks] (:handyman)
|ownersemeritus=[https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes]
|peersemeritus=[mailto:netzen@gmail.com Brian Bondy]
|group=dev-platform
|source_dirs=security/sandbox/win
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - OSX
|description=Sandboxing for the OSX platform
|owner=[mailto:haftandilian@mozilla.com Haik Aftandilian]
|peers=
|group=dev-platform
|source_dirs=security/sandbox/mac
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Linux
|description=Sandboxing for the Linux platform
|owner=[mailto:jld@mozilla.com Jed Davis]
|peers=[mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|group=dev-platform
|source_dirs=security/sandbox/linux
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

===Submodules===
{{Module
|name=Build Config - Fennec
|description=Submodule of the build config covering Fennec's build system in mobile/android.
|owner=[mailto:nalexander@mozilla.com Nicholas Alexander]
|peers=Same as Build Config
|group=dev-builds
|components=Core::Build Config
}}

{{Module
|name=Build Config - Taskgraph
|description=Support for task-graph generation in decision, action, and cron tasks, including configuration of all tasks including those for CI, nightlies, and releases; as well as Docker and VM images used to execute those tasks.
|owner=[mailto:dustin@mozilla.com Dustin Mitchell]
|peers=[mailto:ahal@mozilla.com Andrew Halberstadt], [mailto:aki@mozilla.com Aki Sasaki], [mailto:bstack@mozilla.com Brian Stack], [mailto:mh@glandium.org Mike Hommey], [mailto:gps@mozilla.com Gregory Szorc], [mailto:jmaher@mozilla.com Joel Maher], [mailto:callek@mozilla.com Justin Wood], [mailto:mozilla@hocat.ca Tom Prince]
|components=Firefox Build System::Task Configuration
}}

{{Module
|name=WebRTC Media
|description=Submodule of WebRTC responsible for access to media input devices (microphones, cameras, screen capture), as well as realtime audiovisual codecs and packetization.
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:jib@mozilla.com Jan-Ivar Bruaroey], [mailto:dminor@mozilla.com Dan Minor], [mailto:apehrson@mozilla.com Andreas Pehrson],
|peersemeritus=[mailto:pkerr@mozilla.com Paul Kerr], [mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=/media/webrtc, /dom/media/webrtc, /dom/media/systemservices
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Audio/Video)
}}

{{Module
|name=WebRTC Signaling
|description=Submodule of WebRTC responsible for implementation of PeerConnection API, WebRTC identity, and SDP/JSEP handling
|owner=[mailto:bcampen@mozilla.com Byron Campen]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:abr@mozilla.com Adam Roach], [mailto:rjesup@mozilla.com Randell Jesup], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=/media/webrtc/signaling/
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Signaling)
}}

<noinclude>

===Unassigned Bugzilla Components===

The following Bugzilla components in the Core project have not been assigned to a module (this list is not exhaustive):

<pre>
Core::Find Backend
Core::General
Core::HTML: Form Submission
Core::History: Global
Core::Image Blocking
Core::Localization
Core::Networking: Domain Lists
Core::Selection
Core::Serializers
Core::Spelling checker
Core::X-remote
Core::XUL
</pre>
</noinclude>

Accessibility/Awesome Fetch API

2018-03-21T21:42:58Z

Surkov.alexander: Created page with "=Awesome Fetch API= ==Summary== A bulk data fetching API is designed to * to search the data through a web page * to retrieve portions of a web page in a single call which..."

=Awesome Fetch API=

==Summary==

A bulk data fetching API is designed to
* to search the data through a web page
* to retrieve portions of a web page in a single call

which allows to
* decrease number of calls the AT has to poke into a server
* create buffer-less screen readers
* create lazy and lightweight server implementations

A typical scenarios are
* Navigation: AT fetches next/prev heading while the user moves through a web page
* Read a range: AT reads a paragraph by lines

==Terms and concepts==

Terms:
* Search filters which allows to narrow the data that AT is interested in, for example, find all accessible having a heading role
* Result specifiers which allows to specify what kind of data should be fetched, for example, AT is interested to retrieve accessible names and boundaries
* AOM points (accessible object model aka DOM) which are used to identify and compare ranges in a document. Inspired by DOM point concept.

Also it operates with AT concepts, which are:
* <code>role</code> - a primary characteristic of object like <code>button</code>
* <code>states</code> - boolean characteristics of object like <code>focused</code> or <code>selected</code>
* <code>attributes</code> - a named property having a scalar value (not boolean), for example <code>level:1</code>
* <code>relations</code> - a named property pointing to other object such as <code>label_for</code>
* <code>boundaries</code> - an object boundary in form of a rect
* <code>text</code> - text

==Proposal==

===Search===

====Search filters====

Filter is a boolean expression consisting of conditions combined by boolean operators like: <code>cond1 && cond2 || cond3</code>, where <code>condN</code> is a boolean function which returns true for each accessible object complying a function's criteria.

Suggested boolean functions:
* <code>is(trait)</code> - returns true if an accessible object has a given trait which may be role or state. For example <code>is(listitem) && is(selected)</code> indicates all selected list items.

* <code>has(property[, value])</code> - return true for an accessible object having a property of a value if provided, for example, <code>has(level, 5)</code> stands for all objects having level attribute with value of 5.

A value of <code>has</code> method is not necessary a scalar value. If a property points to an object, then a boolean function can be used as a value. For example, <code>has(controls, is(listbox))</code> will return an object which controls a listbox object.

====Search/Query API====

Search/query is a way to find points or a range complying a search criteria.

<code>
query(AOMPoint anchor, String direction, String searchTerm, AOMPoint start, AOMPoint end)
</code>

to return a a first AOM point complying a search term.

<code>
queryAll(AOMPoint anchor, String direction, String searchTerm, AOMPoint start, AOMPoint end)
</code>

to return a list of all entries complying a search term.

===Data fetching===

====Result specifiers====

Results specifiers are used to scope fetched data. The format is <code>property:value,[value,...]</code>. For example <code>role;states;attributes:level,xml-roles</code> will return role, states, level and xml-roles attribute.

====Data format====

The fetching data is supposed to be in JSON format. For example,
<pre>
[{
role: "heading",
states: [
"invisible", "offscreen"
],
attributes: {
xml-roles: [ "super-button", "lower-button" ]
},
boundaries: [ x, y, width, height ],
text: [
]
},
{
role: "heading",
states: [
"visible", "onscreen"
],
attributes: {
level: 1
},
boundaries: [ x, y, width, height ]
}]
</pre>

====API====

So used to fetch all

<code>
fetch(in AOMPoint start, in AOMPoint end, out String serializedRange)
</code>

returns a string of data of the above format.

Community:SummerOfCode18

2018-02-14T23:06:29Z

Surkov.alexander: /* 2018 Project List */

This is Mozilla's list of green-lit project proposals for the 2018 Google Summer of Code.

<b>Are you a student looking to apply to GSoC with Mozilla?</b> You're in the right place. This page lists all the confirmed [[SummerOfCode|Google Summer of Code]] projects. New suggestions can be made on [[Community:SummerOfCode18:Brainstorming|the Brainstorming page]]. Do not edit this page yourself; contact Mike Hoye or Florian for edits.

If you're interested in participating in Mozilla's GSoC program, you can choose from the list below, '''but you do not have to'''. You can submit a proposal for your own idea. You should look at the [[Community:SummerOfCode18:Brainstorming|guidelines]], though, and discuss your ideas or application in the #introduction channel on IRC.Mozilla.org. This is important, as GSoC projects '''must have''' a supporting member of the Mozilla community to evaluate and mentor them, named in the application.

===Application Advice===

You should do the following:

* Talk to the mentor. Contact details are on this page; if all you have is a nickname, reach out to them on IRC.
* Read the [https://flossmanuals.net/GSoCStudentGuide/ GSoC Student Guide] and follow its advice.
* Read [http://blog.gerv.net/2006/05/how_not_to_apply_for_summer_of/ How Not To Apply For Summer Of Code] and avoid doing the things listed there.
* Read our examples of good applications: [[SummerOfCode/SampleApplications/1|1]], [[SummerOfCode/SampleApplications/2|2]], [[SummerOfCode/SampleApplications/3|3]].
* Apply on [https://summerofcode.withgoogle.com/ the GSoC site] (note that we have an [[SummerOfCode/ApplicationTemplate|application template]]).
* It is entirely acceptable to apply for 2 or 3 projects, if more than one catches your eye; if the applications are high quality, that can improve your chances. Applying to more than that will seem like spam.

Questions about individual projects are best addressed to the potential mentor of that project. These should be listed in the table below. If you want to contact a mentor and contact details are not here, ask people in the #introduction channel on IRC: irc://irc.mozilla.org/#introduction. If you have questions of any other sort, send mail to [mailto:mhoye@mozilla.com Mike Hoye]. He will try and respond promptly and direct your questions to the right person.

===Project List===

* The following projects have been tentatively greenlit, pending milestone clarifications.

== 2018 Project List ==

{| class="standard-table" border="1" style="border-collapse: collapse"
|-
! Title
! Details
! Skills Needed
! Reporter
! Mentor(s)
! Additional Comments
|-
| ReSpec
| [https://github.com/w3c/respec/ ReSpec] is a JS-based tool used to write W3C Specifications (Web Standards) that is widely used by the Web Standards Community. With 5+ years of development, it's heavily depended upon by the W3C community at large (of which Mozilla is an active participant). ReSpec's code is in need of some modernization, optimizations, and bug fixes - and we could use your help! In this project, you would have the opportunity to make ReSpec's UI more accessible, making it leaner and faster using distributed processing with Web Workers, and/or adding new features to make the lives of W3C spec Editor's better.
| Languages or skills needed: JavaScript, HTML, CSS.
| [https://mozillians.org/en-US/u/mcaceres/ Marcos Caceres]
| [https://mozillians.org/en-US/u/mcaceres/ Marcos Caceres]
| ReSpec offers students the opportunity to work on a large code base that has extensive real world use and impact. The project offers students an extensive range of problems to tackle, from UI design, to concurrent processing (using Web Workers to do distributed text processing), dealing with accessibility and internationalization, writing and learning about unit and integration tests, security, code review, etc. - as well as exposure to the W3C and the web standards community, this project also aims at teaching students about how web standards are put together. To determine if this is a project you would like to be part of, see the [https://github.com/w3c/respec/issues/ list of issues] you could work on. It's a great opportunity to learn about all aspects of open source software development, but with the freedom to take on small to large challenges over the Summer (depending on your skill level and level of confidence). About the mentor: Marcos Caceres is a Staff Engineer at Mozilla who has been working on Web Standards for over a decade. Marcos is the lead maintainer of ReSpec. Marcos has extensive experience mentoring developers and has previously successfully mentor a GSO student.
|-
| D3D11 backend for gfx-rs HAL
| [https://github.com/gfx-rs/gfx gfx-rs] is a graphics abstraction library written in Rust and currently used for prototyping and investigation of [https://www.khronos.org/blog/khronos-announces-the-vulkan-portability-initiative Vulkan Portability] and [https://www.w3.org/community/gpu/ WebGPU] by Mozilla. The Hardware Abstraction Layer (HAL) of gfx-rs currently supports Vulkan, D3D12, Metal, and OpenGL. We want it to be powering [https://github.com/servo/webrender/ WebRender] for Firefox Quantum and Servo, and since WebRender currently runs on D3D11 (through [https://chromium.googlesource.com/angle/angle/+/master/README.md Angle]), we need to provide a native D3D11 backend. The implementation can be based off the existing D3D11 code in [https://github.com/gfx-rs/gfx/tree/pre-ll/src/backend/dx11 gfx-rs pre-HAL], and the main challenge is porting the code, optimizing, and ensuring it can successfully run the reference test suite.
| Candidates should be familiar with Rust as well as low-level graphics development. Not having D3D11-specific experience is acceptable, given the willingness to learn it and a properly setup Windows development environment.
| Dzmitry Malyshau (Mozilla)
| Dzmitry Malyshau (Mozilla)
| Proposal Timeline:
* Before April 20: setup the Windows environment for DirectX development; run the examples and reference tests with existing Vulkan/DX12/GL backends; get in contact with developers on [https://gitter.im/gfx-rs/gfx Gitter].
* April 20 – May 23: get familiar with gfx-rs HAL architecture, attempt to fix small entry-level issues and/or write an application/library on top of it.
* May 23 – May 30: setup the backend skeleton with bits of actual logic, such as device initialization, and have it building on CI.
* June 1 – July 5: implement the DX11 logic necessary to run the `quad` example and pass the basic graphics reference tests.
* July 6 - July 31: implement support for compute and tessellation; benchmark the new backend against DX12; pass the full reference test suite.
* Aug 1 - Aug 16: determine the list of capabilities that need to be exposed, merge it with GL backend legacy capabilities, expose to the reference tests.
|-
| Servo: Prototype ways of splitting up the script crate
| [https://github.com/servo/servo/ Servo] is a web rendering engine written in Rust. One specific module contains a huge amount of code that is expensive to compile all at once. This project is intended to explore ways of splitting it into separate modules to achieve better build performance without breaking the complex set of interdependencies that exist in the code.
| Candidates should be familiar with Rust, in particular using it in projects made of multiple crates and relying on features like traits and associated types.
| [https://mozillians.org/en-US/u/jdm/ Josh Matthews] (Mozilla)
| [https://mozillians.org/en-US/u/jdm/ Josh Matthews] (Mozilla)
| [https://github.com/servo/servo/wiki/Prototype-ways-of-splitting-the-script-crate Full project description page]
|-
| web-platform-tests: Improve test manifest workflow and performance
| [https://github.com/w3c/web-platform-tests/ web-platform-tests] is a project for writing a cross-browser test suite, which is used across all major browser engines. The list of tests is stored in a JSON manifest file which is slow to generate and which we currently check in to the Firefox repo. These things create a poor developer experience. The goal of the project is to move to a system where the manifest is downloaded on demand for Firefox developers, and then to explore ways to speed up manifest generation such as employing parallelism or moving performance hotspots to Rust.
| Candidates should be confident programming in Python.
| [https://github.com/jgraham James Graham] (Mozilla)
| [https://github.com/jgraham James Graham] (Mozilla)
| [https://github.com/jgraham/web-platform-tests/wiki/Improve-Test-Manifest-Workflow-and-Performance Full project description page]
|-
| WasmFiddle
| [https://wasdk.github.io/WasmFiddle/ WasmFiddle] is a web application that facilitates learning of the WebAssembly and its usage in the browser. The goal is to create a learning tool that will allow user to quickly start a project that uses WebAssembly, learn based on examples, explore existing popular toolchains (emscripten, rust, etc), etc. The project will be similar to what jsfiddle, jsbin, or codepen proposes, but with additional elements specific to WebAssembly only, e.g. a code generation from C/C++ languages or how the code will be compiled by the browser and run in native machine code.
| Languages or skills needed: JavaScript, HTML, CSS, WebAssembly. Suggested additional technologies: React, Rust, C++.
| Yury Delendik (Mozilla)
| Yury Delendik (Mozilla)
| The project involves extending the functionality of the existing WasmFiddle/WasmExplorer projects to:
* control, inspect and understand every part of the WebAssembly compilation pipeline;
* don’t hide details or add magic build steps;
* users can create, modify, fork and share fiddles, to reduce friction, no accounts;
* influence JavaScript developers through well-thought out examples, best practices and templates;
* add support for many languages: C/C++/Rust/etc;
* create environments where users can play and have fun with: WebGL, Physics, Games, Audio Synthesizers
|-
| Pontoon's path to first contribution
| Pontoon is Mozilla's localization tool, used by hundreds of contributors to translate Firefox, mozilla.org, and many other Mozilla products. It is critical to shipping Firefox to as many users as possible, all around the world. This year, we would like to improve the experience of first-time users of Pontoon. Your task would consist of defining a "path to first contribution", and making it as smooth as possible. That mainly involves adding a tutorial to walk users through the translation interface and reworking the landing page, all of that using recent front-end technologies in a fast-evolving application.
| JavaScript, HTML, CSS, Python, UX. Django and React are pluses
| [https://mozillians.org/en-US/u/adrian/ Adrian Gaudebert] (Mozilla)
| [https://mozillians.org/en-US/u/adrian/ Adrian Gaudebert] (Mozilla)
|-
| AOM - accessibility API
| [https://github.com/WICG/aom/blob/gh-pages/explainer.md AOM] is JavaScript API designed to help the authors to make the web pages accessible, i.e. make them usable by the assisstive technologies such as screen readers, screen magnifiers and others. AOM specification is inspired by [https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA ARIA] standard, an HTML 5 extension, used to add semantics to the web pages. If you are familiar with ARIA, then you can think of AOM as JavaScript ARIA. The AOM proposal (phase 1) was already implemented in Chrome under a flag, and you can help do the same in Firefox.
| Languages or skills needed: C++.
| Alexander Surkov (Mozilla) (surkov.alexander@gmail.com)
| Alexander Surkov (Mozilla) (surkov.alexander@gmail.com)
| This project is the opportunity to hack on the heart of Mozilla Firefox, the Gecko engine. It involves working with a large code base and solving a wide variety of problems, from the solution architecture to finding efficient ways to implement it. If you want to learn about Gecko and accessibility, that's the right place. AOM has the potential of becoming a new standard in making the web page accessible next few years. You can help to happen it sooner.
|-
| metricsgraphics - zooming and brushing
| [https://github.com/mozilla/metricsgraphics metricsgraphics] is JavaScript library designed to help with the presentation of interactive visualization. It is used extensively both inside and outside Mozilla. This project would be about adding a set of zooming and brushing features to facilitate the exploration of large and/or noisy datasets, such as in the [https://wiki.mozilla.org/EngineeringProductivity/Projects/Perfherder Perfherder] or [https://github.com/mozilla/missioncontrol/ Mission Control] projects. Detailed project description to come.
| Languages or skills needed: JavaScript, HTML/SVG
| William Lachance (Mozilla)
| William Lachance (Mozilla)
|
|-
| Iodide Notebook
| The [https://github.com/mozilla/iodide Iodide Notebook] is a pure client-side browser-based IDE and publication tool for scientific computing and computational inquiry using web technologies (HTML, CSS, Javascript, WebAssembly). It provides a Jupyter-style notebook interface, granting scientists full access to the power of the DOM and browser APIs within a familiar iterative workflow, and with zero overhead -- absolutely no software installation and configuration is required, so people can seamlessly learn from and extend the work of others.

Students will contribute to: extending the functionality of the notebook; making the notebook code more robust and performant; helping to shape the user experience; and creating example notebooks.
| JS; HTML; CSS; React/Redux; familiarity with at least one scientific computing language preferred (ex: MATLAB, Mathematica, Julia, Numpy/Scipy, R, etc). Science/math background is a major plus.
| Brendan Colloran (bcolloran@mozilla.com)
| Brendan Colloran (bcolloran@mozilla.com)
| In addition to helping to build the notebook, actively dogfooding it will be an essential part of our work. This means that students with a scientific and/or applied math background will be encouraged to build example notebooks that demonstrate visualizations, simulations, data analyses, etc., on topics of their choosing. In addition to mentoring students on software development, we will provide mentorship in scientific computing and data science.
|
|-
| Improved Pulse Inspector Backend
| [https://github.com/taskcluster/taskcluster-rfcs/issues/104 More details here]. The idea is to create a backend service that will allow browser-side applications like [https://tools.taskcluster.net/pulse-inspector/ pulse inspector] to listen to arbitrary [http://pulseguardian.mozilla.org/ Pulse] messages.
| JavaScript (server-side), AMQP, WebSockets
| Dustin Mitchell (Mozilla)
| Jonas Jensen (Mozilla) / Eli (Perelman Mozilla)
| This project can largely be a generic read-only websocket proxy for RabbitMQ, refer to our [https://github.com/taskcluster/taskcluster-rfcs/issues/104 issue for more details].
|-
| Redash - Improve user experience of [https://sql.telemetry.mozilla.org STMO]
| Mozilla runs an [https://sql.telemetry.mozilla.org/ instance] of the Open Source project [https://github.com/getredash/redash Redash], a data analysis and dashboarding tool that has been customized and configured for use with a number of the Firefox organization's data sets. It provides low barrier access to the vast amount of Firefox Telemetry data (and others) to make product decisions for Firefox and others projects.
| Languages or skills needed: Python, JavaScript, HTML
| [https://mozillians.org/en-US/u/jezdez/ Jannis Leidel (jezdez)] (Mozilla)
| [https://mozillians.org/en-US/u/jezdez/ Jannis Leidel (jezdez)] (Mozilla)
| Knowing SQL or having experience with data analysis is not a hard requirement to work on user experience improvements of the Redash tool itself. Instead this GSoC project is targeted at web developers who enjoy improving tools that have a great impact on how Firefox is developed. Please also see the [https://docs.telemetry.mozilla.org/ Firefox data documentation] for a more detailed [https://docs.telemetry.mozilla.org/tools/stmo.html introduction into Mozilla's Redash instance]. A goal of this GSoC project is to upstream all improvements made to the upstream Redash project when possible.
|-
| Automatically detect web compatibility issues ([https://github.com/marco-c/autowebcompat autowebcompat])
| Build a tool to automatically detect web compatibility issues using machine learning tools.
| Python (knowing Keras or having experience with machine learning is a plus)
| [mailto:marco@mozilla.com Marco (:marco)] (Mozilla)
| [mailto:marco@mozilla.com Marco (:marco)] (Mozilla)
| The project involves collecting data (screenshots of websites in different browsers), labeling it, training a neural network to automatically detect when a website is rendered differently in different browsers.
|-
| Autogeneration of style structs in Servo's style system
| Prototype how to run [https://github.com/rlhunt/cbindgen cbindgen] on Servo's style system [https://github.com/servo/servo/tree/master/components/style/values values module] to auto-generate style struct definitions for C++ and Rust, which would enable the removal of 5k+ [https://github.com/servo/servo/blob/master/components/style/properties/gecko.mako.rs lines] of unsafe and slow Rust <-> C++ conversion code. This can be done on a per-struct basis, so prototyping the general mechanism with a simple one like [https://github.com/servo/servo/blob/master/components/style/properties/longhand/color.mako.rs color] would be the first step, migrating more and more as time goes on.
| Primarily Rust (though no need to be really advanced), probably a bit Python for build system integration, and basic C++ since it needs to get generated.
| [https://github.com/emilio emilio]
| [https://github.com/emilio emilio]
| [https://github.com/servo/servo/wiki/Autogeneration-of-style-structs Full project description]
|-
| Timely Security Analytics
| InfoSec uses the Mozilla Defense Platform, MozDef to aggregate logs and alert on time series. This project seeks to create a structure for extract, transform, load operations (ETL) to process these time series events using MapReduce (Apache Spark). The project will have three milestones:
* Demonstrated ability to load data from Mozilla SCL3, MDC1, MDC2 to GCP or AWS and process in apache spark. Student shall have choice of languages: scala, python, etc.
* Demonstrated ability to reason about the MozDef standard data format using map reduce. Produce anomalies for known incident patterns in AWS CloudTrail logs. ( Example: An IAM user or service account used a service they have never used or logged in from a new GeoLocation / IP address tuple. )
* Demonstrated abilility to reason about non structured data (non-MozDef standard format) and correlate with MozDef structured events.
For more information see: [https://docs.google.com/document/d/1pzVbFw5TM8gG01Jabi4aOxAhiMvHGUHZTG-hV4dtAQs/edit?usp=sharing Google Doc]
| Languages or skills needed: Python, Scala, Javascript, ETL, AWS/GCP, Data Science Fundamentals, Apache Spark, Pig, or other big data.
| [https://mozillians.org/en-US/u/akrug/ Andrew Krug :akrug (mozilla)
| [https://mozillians.org/en-US/u/akrug/ Andrew Krug :akrug (mozilla)
[https://mozillians.org/en-US/u/michalpurzynski/] Michal Purzynski :michal` (mozilla)
| This project represents a unique opportunity to work on one of the only fully open source SIEM projects in the community -- MozDef. The MozDef platform is running in production at Mozilla and ingests 14,000,000 events per year. The current alert system uses time series rules to generate meaningful alerts for the infosec team and Mozilla's Operations Center. We're hoping that with the help of qualified student(s) this rich data set can also generate alerts using basic machine learning techniques. This is a unique opportunity to work on aggregation of disparate sources of data: NSM, CloudTrail, etc. into spark. Real-time alerts over large quantities of data.
|-
| C++ Static Analysis
| Add new checkers specific to our base code.
| Strong C++ experience and clang infrastructure.
| [mailto:s@mozilla.com Sylvestre]
| [mailto:andi@mozilla.com Andi]
| In order to tackle issues during the development phase, Mozilla wrote a [https://hg.mozilla.org/mozilla-central/file/tip/build/clang-plugin bunch of static analyzers checkers] based on [http://clang.llvm.org/extra/clang-tidy/ clang-tidy]. In this project, we will focus on writing more checkers (either generic to C/C++ or specific to Gecko programming patterns).
|-
| Download Spam Protection for Firefox
| In Firefox, we want websites to go through a permission prompt if they want to initiate several downloads in an automated (not user-initiated) fashion. The project will involve implementing a permission prompt, implementing the logic of when it should be triggered, and collecting data (via telemetry, etc) on how users interact with the prompt in order to verify how the feature behaves.
| Good JavaScript experience and a basic understand of how the web works.
| [mailto:jhofmann@mozilla.com Johann (:johannh)]
| [mailto:nhnt11+gsoc@gmail.com Nihanth (:nhnt11)]
| A more detailed description can be found [https://bugzilla.mozilla.org/show_bug.cgi?id=1306334#c2 here]
|-
| TLS scanning in Rust for Mozilla TLS Observatory
| [https://github.com/mozilla/tls-observatory Mozilla TLS Observatory] is a hosted service that provides hindsight and compliance checking on the configuration of HTTPS servers. The goal of this project is to rewrite the [https://github.com/mozilla/cipherscan ciphersuite scanner] in Rust to support scanning TLS 1.3, but also maintain the ability to scan old version of TLS, all the way back to SSL2.0. This will likely require interacting with older versions of OpenSSL.

Performance is also a strong requirement for this project. TLS Observatory scans thousands of sites every hour, and saving precious seconds on each scans make a big difference to the infrastructure.

Finally, because this is a replacement of Cipherscan, this project requires maintaining backward compatibility with integrations that rely on specific flags, or json outputs.

The final goal is to ship this project into the production infrastructure of TLS Observatory.
| Programming skills in C and Rust. Strong understanding of TLS and micro-services architectures.
| [mailto:jvehent@mozilla.com Julien Vehent]
| [mailto:jvehent@mozilla.com Julien Vehent]
| Cipherscan is the measuring tool that Mozilla uses to keep on eye on TLS configurations across the Internet. It is instrumental to the TLS guidelines work we do over at [https://wiki.mozilla.org/Security/Server_Side_TLS Server Side TLS]. This project will directly contribute to tooling that operators rely on worldwide to keep their websites secure.

This is a fairly complex project that requires programming, networking and cryptography skills. Candidates will require skills in all three areas to succeed (GSoC is not long enough to learn them on the go).
|-
| Multi-tab select in Firefox
| This project will focus on adding multiple-select functionality to the tab strip in Firefox. The selected student will teach Firefox to know about multiple tabs being selected, while also adding functionality to close, and move to new window.
| JavaScript, CSS, and web experience
| [mailto:jaws@mozilla.com Jared Wein (:jaws)]
| [mailto:jaws@mozilla.com Jared Wein (:jaws)]
| You can learn more by [https://bugzilla.mozilla.org/show_bug.cgi?id=566510 reading the bug on Bugzilla], but note that the comments there stem back multiple years as people have been wanting this feature for a long time. While working on this you will become very familiar with the [https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox Browser Toolbox], our own "Inspector" tool for the browser user-interface, as well as writing automated tests for the new feature you're adding. Most of our tab-selection code lives within [https://searchfox.org/mozilla-central/source/browser/base/content/tabbrowser.xml our tabbrowser.xml] file, which you can browse around if you're interested to see how some operations work.
|-
| ..your project here!
|
|
|
|
|
|}

Community:SummerOfCode18:Brainstorming

2018-01-18T17:57:57Z

Surkov.alexander:

Mozilla community members - submit proposals here for 2018 Google Summer of Code projects with Mozilla. (If this page looks empty, it's because accepted ideas have already been transferred to the [[Community:SummerOfCode18|official list]].) Our application for summer of 2018 goes into Google on '''January 23rd''', so get those project ideas in quickly.

<b>Are you a student looking to apply to SoC with Mozilla?</b> Your first stop should be the [[Community:SummerOfCode18|official list of ideas]]. This page is full of weird ideas, some of which are still on here for a reason - it could be that they are not properly defined, the wrong size, or don't have a mentor. That makes them less likely to get accepted. You <i>can</i>, of course, also submit your own ideas - you don't have to put an idea on this page and get it 'made official' in order to send in a proposal for it.

==How To Write A Good Project Proposal==

Before adding an proposal to this list, please consider the following:

* '''Be specific'''. It's hard to understand the impact of, or the size of, vague proposals.
* '''Consider size'''. The student has eight weeks to design, code, test and document the proposal. It needs to fill, but not overfill, that time.
* '''Do your research'''. Support the idea with well-researched links.
* '''Don't morph other people's ideas'''. If you have a related idea, place it next to the existing one, or add a comment.
* '''Insert only your own name into the Mentor column''', and then only if you are willing to take on the responsibility. If you think the SoC admins won't know who you are, leave contact details.
* '''Check back regularly'''. The administrators may have questions about your idea that you will need to answer.
* '''Know when to give up'''. If you've added the same idea for the last three years and it hasn't made it to the official page, perhaps you can predict what will happen this time.

==Suggestion List==

[[SummerOfCode|Here are the ideas lists from previous years]].

Proposals can be in almost any part of the Mozilla project - don't be fooled by the "Code" in "Summer of Code". If there is no category below for your part of Mozilla, add one!

Here is the template for adding project proposals. Feel free to add new proposal to existing general categories, or add new categories as appropriate.

== General category or project name ==

{| class="standard-table" border="1" style="border-collapse: collapse"
|-
! Title
! Details
! Skills Needed
! Reporter
! Mentor(s)
! Comments
|-
| Title of your proposal
| A few sentences describing the project.
| Languages or skills needed
| Project submitter's info
| Project mentor's info
| Anything else people might need to know about this submission.
|-
| ReSpec
| [https://github.com/w3c/respec/ ReSpec] is a JS-based tool used to write W3C Specifications (Web Standards) that is widely used by the Web Standards Community. With 5+ years of development, it's heavily depended upon by the W3C community at large (of which Mozilla is an active participant). ReSpec's code is in need of some modernization, optimizations, and bug fixes - and we could use your help! In this project, you would have the opportunity to make ReSpec's UI more accessible, making it leaner and faster using distributed processing with Web Workers, and/or adding new features to make the lives of W3C spec Editor's better.
| Languages or skills needed: JavaScript, HTML, CSS.
| Marcos Caceres (Mozilla)
| Marcos Caceres (Mozilla)
| ReSpec offers students the opportunity to work on a large code base that has extensive real world use and impact. The project offers students an extensive range of problems to tackle, from UI design, to concurrent processing (using Web Workers to do distributed text processing), dealing with accessibility and internationalization, writing and learning about unit and integration tests, security, code review, etc. - as well as exposure to the W3C and the web standards community, this project also aims at teaching students about how web standards are put together. To determine if this is a project you would like to be part of, see the [https://github.com/w3c/respec/issues/ list of issues] you could work on. It's a great opportunity to learn about all aspects of open source software development, but with the freedom to take on small to large challenges over the Summer (depending on your skill level and level of confidence). About the mentor: Marcos Caceres is a Staff Engineer at Mozilla who has been working on Web Standards for over a decade. Marcos is the lead maintainer of ReSpec. Marcos has extensive experience mentoring developers and has previously successfully mentor a GSO student.
|-
| D3D11 backend for gfx-rs HAL
| [https://github.com/gfx-rs/gfx gfx-rs] is a graphics abstraction library written in Rust and currently used for prototyping and investigation of [https://www.khronos.org/blog/khronos-announces-the-vulkan-portability-initiative Vulkan Portability] and [https://www.w3.org/community/gpu/ WebGPU] by Mozilla. The Hardware Abstraction Layer (HAL) of gfx-rs currently supports Vulkan, D3D12, Metal, and OpenGL. We want it to be powering [https://github.com/servo/webrender/ WebRender] for Firefox Quantum and Servo, and since WebRender currently runs on D3D11 (through [https://chromium.googlesource.com/angle/angle/+/master/README.md Angle]), we need to provide a native D3D11 backend. The implementation can be based off the existing D3D11 backend of [https://github.com/gfx-rs/gfx/tree/pre-ll/src/backend/dx11 gfx-rs pre-HAL], and the main challenge is porting the code, optimizing, and testing it.
| Candidates should be familiar with Rust as well as low-level graphics development. Not having D3D11-specific experience is acceptable, given the willingness to learn it and a properly setup Windows development environment.
| Dzmitry Malyshau (Mozilla)
| Dzmitry Malyshau (Mozilla)
| gfx-rs is one of the foundational projects in Rust gamedev/graphics, with rich history and wide range of users. We have an active community that encourages learning and curiosity in how graphics works down to the hardware. This is not a Mozilla project, but it may become a key component in Firefox Quantum for the ability to run natively on different platforms, while utilizing the fine-grained control of the graphics/compute workloads exposed by the low-level APIs.
|-
| Servo: Prototype ways of splitting up the script crate
| [https://github.com/servo/servo/ Servo] is a web rendering engine written in Rust. One specific module contains a huge amount of code that is expensive to compile all at once. This project is intended to explore ways of splitting it into separate modules to achieve better build performance without breaking the complex set of interdependencies that exist in the code.
| Candidates should be familiar with Rust, in particular using it in projects made of multiple crates and relying on features like traits and associated types.
| [https://mozillians.org/en-US/u/jdm/ Josh Matthews] (Mozilla)
| [https://mozillians.org/en-US/u/jdm/ Josh Matthews] (Mozilla)
| [https://github.com/servo/servo/wiki/Prototype-ways-of-splitting-the-script-crate Full project description page]
|-
| web-platform-tests: Improve test manifest workflow and performance
| [https://github.com/w3c/web-platform-tests/ web-platform-tests] is a project for writing a cross-browser test suite, which is used across all major browser engines. The list of tests is stored in a JSON manifest file which is slow to generate and which we currently check in to the Firefox repo. These things create a poor developer experience. The goal of the project is to move to a system where the manifest is downloaded on demand for Firefox developers, and then to explore ways to speed up manifest generation such as employing parallelism or moving performance hotspots to Rust.
| Candidates should be confident programming in Python.
| [https://github.com/jgraham James Graham] (Mozilla)
| [https://github.com/jgraham James Graham] (Mozilla)
|-
| WasmFiddle
| [https://wasdk.github.io/WasmFiddle/ WasmFiddle] is a web application that facilitates learning of the WebAssembly and its usage in the browser. The goal is to create a learning tool that will allow user to quickly start a project that uses WebAssembly, learn based on examples, explore existing popular toolchains (emscripten, rust, etc), etc. The project will be similar to what jsfiddle, jsbin, or codepen proposes, but with additional elements specific to WebAssembly only, e.g. a code generation from C/C++ languages or how the code will be compiled by the browser and run in native machine code.
| Languages or skills needed: JavaScript, HTML, CSS, WebAssembly. Suggested additional technologies: React, Rust, C++.
| Yury Delendik (Mozilla)
| Yury Delendik (Mozilla)
| The project involves extending the functionality of the existing WasmFiddle/WasmExplorer projects to:
* control, inspect and understand every part of the WebAssembly compilation pipeline;
* don’t hide details or add magic build steps;
* users can create, modify, fork and share fiddles, to reduce friction, no accounts;
* influence JavaScript developers through well-thought out examples, best practices and templates;
* add support for many languages: C/C++/Rust/etc;
* create environments where users can play and have fun with: WebGL, Physics, Games, Audio Synthesizers
|-
| Pontoon's path to first contribution
| Pontoon is Mozilla's localization tool, used by hundreds of contributors to translate Firefox, mozilla.org, and many other Mozilla products. It is critical to shipping Firefox to as many users as possible, all around the world. This year, we would like to improve the experience of first-time users of Pontoon. Your task would consist of defining a "path to first contribution", and making it as smooth as possible. That mainly involves adding a tutorial to walk users through the translation interface and reworking the landing page, all of that using recent front-end technologies in a fast-evolving application.
| JavaScript, HTML, CSS, Python, UX. Django and React are pluses
| [https://mozillians.org/en-US/u/adrian/ Adrian Gaudebert] (Mozilla)
| [https://mozillians.org/en-US/u/adrian/ Adrian Gaudebert] (Mozilla)
|
|-
| AOM - accessibility API
| [https://github.com/WICG/aom/blob/gh-pages/explainer.md AOM] is JavaScript API designed to help the authors to make the web pages accessible, i.e. make them usable by the assisstive technologies such as screen readers, screen magnifiers and others. AOM specification is inspired by [https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA ARIA] standard, an HTML 5 extension, used to add semantics to the web pages. If you are familiar with ARIA, then you can think of AOM as JavaScript ARIA. The AOM proposal (phase 1) was already implemented in Chrome under a flag, and you can help do the same in Firefox.
| Languages or skills needed: C++.
| Alexander Surkov (Mozilla)
| Alexander Surkov (Mozilla)
| This project is the opportunity to hack on the heart of Mozilla Firefox, the Gecko engine. It involves working with a large code base and solving a wide variety of problems, from the solution architecture to finding efficient ways to implement it. If you want to learn about Gecko and accessibility, that's the right place. AOM has the potential of becoming a new standard in making the web page accessible next few years. You can help to happen it sooner.
|-
| Another proposal, etc.
|
|
|
|
|
|}

Modules/Core

2017-11-28T13:23:16Z

Surkov.alexander:

<noinclude>
'''Only module owners may edit this page.'''

They may:

* update any information about their module except the name of the owner
* add or remove sub-modules
* change the owner of a sub-module
* add emeritus owners or peers

Other changes, including changes of module owner or addition/removal of modules, must be agreed with the Module Ownership Module group, probably via a discussion in [https://www.mozilla.org/about/forums/#governance mozilla.governance].
</noinclude>
{{Module
|name=Accessibility
|description=Support for platform accessibility APIs. Accessibility APIs are used by 3rd party software like screen readers, screen magnifiers, and voice dictation software, which need information about document content and UI controls, as well as important events like changes of focus.
|owner=[mailto:surkov.alexander@gmail.com Alexander Surkov]
|peers=[mailto:dbolter@mozilla.com David Bolter], [mailto:eitan@monotonous.org Eitan Isaacson], [mailto:jteh@mozilla.com James Teh], [mailto:mzehe@mozilla.com Marco Zehe], [mailto:yzenevich@mozilla.com Yura Zenevich]
|ownersemeritus=[mailto:aaron@moonset.net. Aaron Leventhal]
|peersemeritus=[mailto:tbsaunde+mozbugs@tbsaunde.org Trevor Saunders], [mailto:ginn.chen@oracle.com Ginn Chen], Evan Yan
|group=dev-accessibility
|source_dirs=accessible/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=Browser WebAPI
|description=Web API for rendering apps, browser windows and widgets.
|owner=[mailto:kchen@mozilla.com Kan-Ru Chen]
|peers=[mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:fabrice@mozilla.com Fabrice Desré]
|group=dev-webapi
|source_dirs=dom/browser-element/
|url=
|components=Core::DOM
}}

{{Module
|name=Build and Release Tools
|description=Tools related to build and release automation and configuration of release builds.
|owner=[mailto:nthomas@mozilla.com Nick Thomas]
|peers=[mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:coop@mozilla.com Chris Cooper]
|group=release-engineering
|source_dirs=browser/config/mozconfigs/, mobile/android/config/mozconfigs/, xulrunner/config/mozconfigs/, b2g/config/, tools/update-packaging/
|url=https://wiki.mozilla.org/ReleaseEngineering
|components=Release Engineering::*
}}

{{Module
|name=Build Config
|description=The build system for Gecko and several mozilla.org hosted Gecko-based applications.
|owner=[mailto:gps@mozilla.com Gregory Szorc] (:gps)
|peers=[mailto:mh@glandium.org Mike Hommey] (:glandium), [mailto:mshal@mozilla.com Mike Shal] (:mshal), [mailto:ted@mielczarek.org Ted Mielczarek] (:ted), [mailto:cmanchester@mozilla.com Chris Manchester](:chmanchester), [mailto:nfroyd@mozilla.com Nathan Froyd] (:froydnj), [mailto:rgiles@mozilla.com Ralph Giles] (:rillian)
|ownersemeritus=Ted Mielczarek (2008-[https://blog.mozilla.org/ted/2013/03/07/gregory-szorc-is-now-the-build-config-module-owner/ 2013]), Benjamin Smedberg (???-[http://benjamin.smedbergs.us/blog/2008-04-30/more-changing-of-the-guard-ted-mielczarek/ 2008]),
|group=dev-builds
|source_dirs=build/, config/, python/mozbuild, tools/cross-commit, tools/cvs2hg-import.py, tools/cvsmgmt/, tools/elf-dynstr-gc/, tools/trees.pl, browser/config/mozconfigs/, mobile/config/mozconfigs/, xulrunner/config/mozconfigs/
|url=http://www.mozilla.org/build/
|components=Core::Build Config
}}

{{Module
|name=Code Analysis and Debugging Tools
|description=Tools for debugging Mozilla code or for analyzing speed, memory use, and other characteristics of it.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=
|group=dev-performance
|source_dirs=tools/codesighs/, tools/debug/, tools/dreftool/, tools/dumpdeps/, tools/footprint/, tools/jprof/, tools/leaky/, tools/memory/, tools/module-deps/, tools/performance/, tools/post_compile/, tools/preloader/, tools/rb/, tools/reorder/, tools/trace-malloc/, tools/uuiddeps/,
|url=
|components=
}}

{{Module
|name=Content HTTP Headers
|description=HTTP headers related to content, e.g. User-Agent, Content-Type, Accept. (Transport-related headers are the responsibility of the Necko module owner.)
|owner=[mailto:gerv@mozilla.org Gervase Markham]
|peers=[mailto:lmandel@mozilla.com Lawrence Mandel]
|group=dev-platform
|source_dirs=
|url=https://developer.mozilla.org/en/Gecko_user_agent_string_reference
|components=Core::Networking: HTTP
}}

{{Module
|name=Content Security
|description=Native content-based security features, including: Content Security Policy (CSP), Mixed Content Blocker (MCB), Subresource Integrity (SRI) and CORS.
|owner=[mailto:ckerschbaumer@mozilla.com Christoph Kerschbaumer]
|peers=[mailto:francois@mozilla.com François Marier], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:tvyas@mozilla.com Tanvi Vyas], [mailto:dveditz@mozilla.com Dan Veditz], [mailto:mozilla@sidstamm.com Sid Stamm]
|group=dev-security
|source_dirs=dom/security
|components=Core::DOM: Security
}}

{{Module
|name=Cookies and Permissions
|description=
|owner=Monica Chew
|peers=[mailto:josh@joshmatthews.com Josh Matthews], [mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:mconnor@steelgryphon.com Mike Connor], [mailto:dwitte@gmail.com Dan Witte], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sdwilsh@shawnwilsher.com Shawn Wilsher (ping on irc)]
|group=dev-tech-network
|source_dirs=extensions/cookie/, netwerk/cookie/
|url=
|components=Core::Networking: Cookies
}}
{{Module
|name=Cycle Collector
|description=Code to break and collect objects within reference cycles
|owner=[https://mozillians.org/en-US/u/mccr8/ Andrew McCreight]
|peers=Peter Van der Beken, Olli Pettay, David Baron
|source_dirs=xpcom/base/nsCycleCollector.* and some support headers
|components=Core::XPCOM
|group=dev-platform
}}
{{Module
|name=C++/Rust usage, tools, and style
|description=Aspects of C++ use such as language feature usage, standard library versions/usage, compiler/toolchain versions, formatting and naming style, and aspects of Rust use as needs arise
|owner=[mailto:nfroyd@mozilla.com Nathan Froyd] (while Ehsan is away)
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:glandium@mozilla.com Mike Hommey], [mailto:jwalden@mozilla.com Jeff Walden], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|source_dirs=non-third-party C++ and Rust code in the tree
|components=Various components
|group=dev-platform
}}
{{Module
|name=docshell
|description=
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:sawang@mozilla.com Samael Wang]
|peersemeritus=[mailto:jstenback@gmail.com Johnny Stenback],[mailto:cbiesinger@gmail.com Christian Biesinger],[mailto:justin.lebar@gmail.com Justin Lebar]
|group=dev-platform
|source_dirs=docshell/, uriloader/
|url=
|components=Core::Document Navigation
}}

{{Module
|name=Document Object Model
|description=
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:hsivonen@iki.fi Henri Sivonen], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:baku@mozilla.com Andrea Marchesini],
[mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:bkelly@mozilla.com Ben Kelly], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:kyle@nonpolynomial.com Kyle Machulis]
|ownersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|peersemeritus=[mailto:justin.lebar@gmail.com Justin Lebar], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:bent.mozilla@gmail.com Ben Turner], [mailto:mounir@lamouri.fr Mounir Lamouri (still active, but slower to respond than previously)], [mailto:me@kylehuey.com Kyle Huey]
|group=dev-tech-dom
|source_dirs=dom/*, except directories covered by other modules
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM, Core::DOM: CSS Object Model, Core::DOM: Core & HTML
}}

{{Module
|name=DOM File
|description=DOM Blob, File and FileSystem APIs
|owner=[mailto:amarchesini@Mozilla.com Andrea Marchesini]
|peers=[mailto:olli@pettay.fi Olli Pettay]
|group=dev-platform
|source_dirs=dom/file, dom/filesystem
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: File
}}

{{Module
|name=Event Handling
|description=DOM Events and Event Handling
|owner=[mailto:olli@pettay.fi Olli Pettay], [mailto:masayuki@d-toybox.com Masayuki Nakano]
|peers=[mailto:sshih@mozilla.com Stone Shih]
|group=dev-platform
|source_dirs=dom/events and event handling related code elsewhere
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: Events, Core::Event Handling
}}

{{Module
|name=Web Workers
|description=
|owner=[mailto:baku@mozilla.com Andrea Marchesini]
|peers=[mailto:mrbkap@mozilla.com Blake Kaplan], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey], [mailto:bkelly@mozilla.com Ben Kelly]
|ownersemeritus=[mailto:bent.mozilla@gmail.com Ben Turner]
|group=dev-platform
|source_dirs=dom/workers/
|url=https://developer.mozilla.org/En/Using_web_workers
|components=Core::DOM: Workers
}}

{{Module
|name=IndexedDB
|description=
|owner=[mailto:jvarga@mozilla.com Jan Varga]
|peers=[mailto:btseng@mozilla.com Bevis Tseng], [mailto:bugmail@asutherland.org Andrew Sutherland], [mailto:baku@mozilla.com Andrea Marchesini]
|ownersemeritus=[mailto:bent.mozilla@gmail.com Ben Turner]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey]
|group=dev-platform
|source_dirs=dom/indexedDB/
|url=https://developer.mozilla.org/en/IndexedDB
|components=Core::DOM: IndexedDB
}}

{{Module
|name=Editor
|description=
|owner=[mailto:masayuki@d-toybox.com Masayuki Nakano]
|peers=
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=editor/
|url=http://www.mozilla.org/editor/
|components=Core::Editor
}}

{{Module
|name=Embedding
|description=Gecko embedding APIs and frameworks
|owner=[mailto:myk@mykzilla.org Myk Melez]
|ownersemeritus=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:bdahl@mozilla.com Brendan Dahl], [mailto:tbsaunde@tbsaunde.org Trevor Saunders]
|peersemeritus=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-platform
|source_dirs=embedding/
|url=
|components=Core::Embedding: APIs
}}

{{Module
|name=Find As You Type
|description=Find As You Type (formerly called Type Ahead Find) is a feature that allows quick web page navigation when you type a succession of characters in the body of the displayed page (not in an edit box of or drop down list). Currently seeks new owner.
|owner=
|peers=
|group=dev-accessibility
|source_dirs=extensions/typeaheadfind/
|url=http://www.mozilla.org/access/type-ahead/
|components=
}}

{{Module
|name=Gecko Profiler
|description=Gecko's built-in profiler
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:nnethercote@mozilla.com Nicholas Nethercote], [mailto:jseward@mozilla.com Julian Seward] (LUL), [mailto:kvijayan@mozilla.com Kannan Vijayan] (JS integration), [mailto:shu@mozilla.com Shu-yu Guo] (JS integration), [mailto:tlee@mozilla.com Thinker Lee] (TaskTracer), [mailto:cyu@mozilla.com Cervantes Yu] (TaskTracer), [mailto:b56girard@gmail.com Benoit Girard].
|group=dev-platform
|source_dirs=tools/profiler/
|url=https://developer.mozilla.org/en-US/docs/Mozilla/Performance/Profiling_with_the_Built-in_Profiler
|components=Core::Gecko Profiler
}}

{{Module
|name=Geolocation
|description=Implementation of the Geolocation W3C Spec, location provider apis, and wifi scanning code.
|owner=[mailto:josh@joshmatthews.net Josh Matthews], [mailto:kchen@mozilla.com Kan-Ru Chen]
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner], Garvan Keeley
|peers=
|group=dev-tech-dom
|source_dirs=dom/geolocation, dom/system/, netwerk/wifi
|url=https://developer.mozilla.org/En/Using_geolocation
|components=Core::Geolocation
}}

{{Module
|name=Global Key Bindings
|description=Global hot keys in Mozilla for the browser, editor, mail-news and widgets. Does not include underlined menu accelerators and the like, as those are part of i18n.
|owner=Aaron Leventhal
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|group=dev-accessibility
|source_dirs=dom/xbl/builtin/
|url=http://www.mozilla.org/projects/ui/accessibility/mozkeyintro.html
|components=Core::Keyboard: Navigation
}}

{{Module
|name=Graphics
|description=Mozilla graphics API
|owner=[mailto:jrmuizel@mozilla.com Jeff Muizelaar](Thebes, QCMS, YCbCr, Cairo/Pixman, Regions, OS X, Other)
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:jdrew@mozilla.com Joe Drew], [mailto:vladimir@pobox.com Vladimir Vukicevic], [mailto:bas.schouten@live.nl Bas Schouten](Layers, Windows), [mailto:bjacob@mozilla.com Benoit Jacob](gfx/gl), [mailto:bgirard@mozilla.com Benoit Girard](Compositor, Performance), [mailto:ajuma.bugzilla@alijuma.com Ali Juma], [mailto:jgilbert@mozilla.com Jeff Gilbert](WebGL, ANGLE), [mailto:george@mozilla.com George Wright](Canvas2D), [mailto:mwoodrow@mozilla.com Matt Woodrow](Layers API), [mailto:jdaggett@mozilla.com John Daggett](text/fonts), [mailto:jfkthame@googlemail.com Jonathan Kew](text/fonts), [mailto:nsilva@mozilla.com Nicolas Silva](MozSurface), [mailto:ncameron@mozilla.com Nick Cameron], [mailto:sikeda@mozilla.com Sotaro Ikeda](B2G), [mailto:snorp@mozilla.com James Willcox](Android), [mailto:clord@mozilla.com Christopher Lord], [mailto:mstange@themasta.com Markus Stange](OS X), [mailto:lsalzman@mozilla.com Lee Salzman](Skia), [mailto:mchang@mozilla.com Mason Chang], [mailto:dvander@mozilla.com David Anderson]
|group=dev-platform
|source_dirs=gfx/, dom/canvas/
|url=https://wiki.mozilla.org/Platform/GFX https://wiki.mozilla.org/Gecko:Layers https://wiki.mozilla.org/Gecko:2DGraphicsSketch
|components=Core::Graphics, Core::Graphics: Layers, Core::Graphics: Text, Core::GFX: Color Management, Core::Canvas: 2D, Core::Canvas: WebGL
}}

{{Module
|name=APZ (Graphics submodule)
|description=Asynchronous panning and zooming
|owner=[mailto:kgupta@mozilla.com Kartikaya Gupta]
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:tnikkel@mozilla.com Timothy Nikkel], [mailto:dvander@mozilla.com David Anderson], [mailto:mstange@mozilla.com Markus Stange]
|group=dev-platform
|source=gfx/layers/apz
|url=https://wiki.mozilla.org/Platform/GFX/APZ
|components=Core::Panning and Zooming
}}

{{Module
|name=Moz2D (Graphics submodule)
|description=Platform independent 2D graphics API
|owner=[mailto:bschouten@mozilla.com Bas Schouten]
|peers=[mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:gwright@mozilla.com George Wright], [mailto:jwatt@jwatt.org Jonathan Watt]
|group=dev-platform
|source=gfx/2d
|url=https://wiki.mozilla.org/Platform/GFX/Moz2D
|components=Core::Graphics
}}

{{Module
|name=Legacy HTML Parser
|description=
|owner=[mailto:mrbkap@gmail.com Blake Kaplan]
|peers=[mailto:dbaron@dbaron.org David Baron], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:rbs@maths.uq.edu.au rbs@maths.uq.edu.au]
|peersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|source_dirs=parser/htmlparser
|url=http://www.mozilla.org/newlayout/doc/parser.html
|components=Core::HTML: Parser
}}

{{Module
|name=HAL
|description=Hardware Abstraction Layer
|owner=[https://mozillians.org/u/dhylands/ Dave Hylands]
|peers=[mailto:gsvelto@mozilla.com Gabriele Svelto]
|group=dev-platform
|source_dirs=hal/
|components=Core::Hardware Abstraction Layer (HAL)
}}

{{Module
|name=HTML Parser
|description=The HTML Parser transforms HTML source code into a DOM. It conforms to the HTML specification, and is mostly translated automatically from Java to C++.
|owner=[mailto:hsivonen@iki.fi Henri Sivonen]
|peers=[mailto:wchen@mozilla.com William Chen]
|group=dev-platform
|source_dirs=parser/html
|url=http://about.validator.nu/
|components=Core::HTML: Parser
}}

{{Module
|name=I18N Library
|description=
|owner=[mailto:jshin1987@gmail.com Jungshik Shin], [mailto:smontagu@smontagu.org Simon Montagu]
|peers=[mailto:VYV03354@nifty.ne.jp Masatoshi Kimura]
|group=dev-i18n
|source_dirs=intl/
|url=http://mozilla.org/projects/intl/index.html
|components=Core::Internationalization
}}

{{Module
|name=ImageLib
|description=
|owner=[mailto:tnikkel@gmail.com Timothy Nikkel]
|peers=[mailto:aosmond@mozilla.com Andrew Osmond], [mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:seth.bugzilla@blackhail.net Seth Fowler]
|peersemeritus=[mailto:netzen@gmail.com Brian Bondy], [mailto:justin.lebar@gmail.com Justin Lebar]
|group=dev-platform
|source_dirs=media/libjpeg/, media/libpng/, image/, modules/zlib/
|url=
|components=Core::ImageLib
}}

{{Module
|name=IPC
|description=Message-passing between threads and processes
|owner=[mailto:wmccloskey@mozilla.com Bill McCloskey]
|peers=[mailto:danderson@mozilla.com David Anderson], [mailto:kchen@mozilla.com Kan-Ru Chen], [mailto:jld@mozilla.com Jed Davis], [mailto:nfroyd@mozilla.com Nathan Froyd], [mailto:bkelly@mozilla.com Ben Kelly], [mailto:amccreight@mozilla.com Andrew McCreight]
|group=dev-platform
|source_dirs=ipc/glue/, ipc/ipdl/, ipc/chromium/
|url=
|components=Core::IPC}}

{{Module
|name=JavaScript
|description=JavaScript engine (SpiderMonkey)
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:jdemooij@mozilla.com Jan de Mooij], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:nnethercote@mozilla.com Nick Nethercote], [mailto:jwalden@mit.edu Jeff Walden], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:evilpies@gmail.com Tom Schuster], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:till@tillschneidereit.net Till Schneidereit], [mailto:efaust@mozilla.com Eric Faust], [mailto:nfitzgerald@mozilla.com Nick Fitzgerald], [mailto:luke@mozilla.com Luke Wagner], [mailto:arai.unmht@gmail.com Tooru Fujisawa], [mailto:sunfish@mozilla.com Dan Gohman], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:nmatsakis@mozilla.com Niko Matsakis], [mailto:ejpbruel@mozilla.com Eddy Bruel], [mailto:danderson@mozilla.com David Anderson], [mailto:igor@mir2.org Igor Bukanov], [mailto:brendan@mozilla.org Brendan Eich], Andreas Gal
|group=dev-tech-js-engine
|source_dirs=js/src
|url=http://www.mozilla.org/js/spidermonkey,
http://developer.mozilla.org/en/docs/About_JavaScript
|components=Core::JavaScript Engine
}}

{{Module
|name=JavaScript JIT
|description=JavaScript engine's JIT compilers (IonMonkey, Baseline)
|owner=[mailto:jdemooij@mozilla.com Jan de Mooij]
|peers=[mailto:danderson@mozilla.com David Anderson], [mailto:bbouvier@mozilla.com Benjamin Bouvier], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:nicolas.b.pierron@mozilla.com Nicolas Pierron], [mailto:evilpies@gmail.com Tom Schuster], [mailto:sstangl@mozilla.com Sean Stangl], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:luke@mozilla.com Luke Wagner]
|group=dev-tech-js-engine-internals
|source_dirs=js/src/jit
|url=http://www.mozilla.org/js/spidermonkey
|components=Core::JavaScript Engine: JIT
}}

{{Module
|name=JavaScript Debugger Backend
|description=JavaScript debugging hooks
|owner=[mailto:timeless@mozdev.org Josh 'timeless' Soref]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:rginda@hacksrus.com Rob Ginda]
|group=dev-apps-js-debugger
|source_dirs=js/jsd/
|url=http://www.mozilla.org/js/jsd
|components=Other Applications::Venkman JS Debugger
}}

{{Module
|name=jsat
|description=Javascript screen reader that is used in Android and B2G
|owner=[mailto:eitan@monotonous.org Eitan Isaacson]
|peers=[mailto:yzenevich@mozilla.com Yura Zenevich]
|group=dev-accessibility
|source_dirs=accessible/jsat/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=js-ctypes
|description=A foreign function interface which allows privileged JS code to interact with binary code without using XPCOM/XPConnect.
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:bobbyholley@gmail.com Bobby Holley]
|group=dev-tech-js-engine
|source_dirs=js/src/ctypes/
|url=https://wiki.mozilla.org/JSctypes
|components=Core::js-ctypes
}}

{{Module
|name=js-tests
|description=JavaScript test suite
|owner=[mailto:bclary@bclary.com Bob Clary]
|peers=
|group=dev-tech-js-engine
|source_dirs=js/tests/
|url=http://www.mozilla.org/js/tests/library.html
|components=
}}

{{Module
|name=Layout Engine
|description=rendering tree construction, layout (reflow), etc.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:jfkthame@gmail.com Jonathan Kew], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:matt.woodrow@gmail.com Matt Woodrow], [mailto:xidorn+moz@upsuper.org Xidorn Quan]
|group=dev-tech-layout
|source_dirs=layout/%, layout/base/, layout/build/, layout/doc/, layout/forms/, layout/generic/, layout/html/, layout/printing/, layout/tables/, layout/tools/
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout, Core::Layout: Block and Inline, Core::Layout: Floats, Core::Layout: Form Controls, Core::Layout: HTML Frames, Core::Layout: Images, Core::Layout: Misc Code, Core::Layout: R & A Pos, Core::Layout: Tables, Core::Layout: Text, Core::Print Preview, Core::Printing: Output
}}

{{Module
|name=libjar
|description=The JAR handling code (protocol handler, stream implementation, and zipreader/zipwriter).
|owner=[mailto:mwu@mozilla.com Michael Wu]
|peers=[mailto:aklotz@mozilla.com Aaron Klotz]
|group=dev-platform
|source_dirs=modules/libjar
|url=
|components=
}}

{{Module
|name=MathML
|description=MathML is a low-level specification for describing mathematics which provides a foundation for the inclusion of mathematical expressions in Web pages.
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan]
|group=dev-tech-mathml
|source_dirs=layout/mathml/
|url=http://www.mozilla.org/projects/mathml/
|components=Core::MathML
}}

{{Module
|name=Media Playback
|description=HTML Media APIs, including Media Source Extensions and non-MSE video/audio element playback, and Encrypted Media Extensions. (WebRTC and WebAudio not included).
|owner=[mailto:cpearce@mozilla.com Chris Pearce]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:ajones@mozilla.com Anthony Jones], [mailto:kinetik@flim.org Matthew Gregan], [mailto:eflores@mozilla.com Edwin Flores], [mailto:jyavenard@mozilla.com Jean-Yves Avenard], [mailto:gsquelart@mozilla.com Gerald Squelart], [mailto:rgiles@mozilla.com Ralph Giles], [mailto:jwwang@mozilla.com JW Wang]
|group=dev-media
|source_dirs=dom/media, media/gmp-clearkey/, media/libcubeb/, media/libnestegg/, media/libogg/, media/libopus/, media/libstagefright/, media/libtheora/, media/libtremor/, media/libvorbis/, media/libvpx/, media/omx-plugin/, media/rlz/
|url=
|components=Core::Audio/Video
}}

{{Module
|name=Media Transport
|description=Pluggable transport for real-time media
|owner=[mailto:ekr@rtfm.com Eric Rescorla]
|peers=[mailto:bcampen@mozilla.com Byron Campen], [mailto:abr@mozilla.com Adam Roach], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|group=dev-media
|source_dirs=media/mtransport
|url=
|components=Core::WebRTC::Networking
}}

{{Module
|name=Memory Allocator
|description=Most things related to memory allocation in Gecko, including jemalloc, replace-malloc, DMD (dark matter detector), logalloc, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:n.nethercote@gmail.com Nicholas Nethercote], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-platform
|source_dirs=memory/
|components=Core::DMD, Core::jemalloc
}}

{{Module
|name=mfbt
|description=mfbt is a collection of headers, macros, data structures, methods, and other functionality available for use and reuse throughout all Mozilla code (including SpiderMonkey and Gecko more broadly).
|owner=[mailto:jwalden@mit.edu Jeff Walden]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd], [mailto:Ms2ger@gmail.com Ms2ger], [mailto:mh+mozilla@glandium.org Mike Hommey]
|group=dev-platform
|source_dirs=mfbt/
|url=
|components=Core::MFBT
}}

{{Module
|name=mozApps API & UI
|description=Implementation of the navigator.mozApps API
|owner=[mailto:fabrice@mozilla.com Fabrice Desré], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:myk@mozilla.org Myk Melez], [mailto:mar.castelluccio@studenti.unina.it Marco Castelluccio], [mailto:ferjmoreno@gmail.com Fernando Jiménez]
|group=dev-webapi
|source_dirs=dom/apps/, dom/interfaces/apps, product specific files implementing UI hooks.
|url=
|components=Core::DOM: Apps
}}

{{Module
|name=Mozglue
|description=Glue library containing various low-level functionality, including a dynamic linker for Android, a DLL block list for Windows, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd] (mozglue/linker), [mailto:kgupta@mozilla.com Kartikaya Gupta] (mozglue/android), [mailto:nchen@mozilla.com Jim Chen] (mozglue/android)
|group=dev-platform
|source_dirs=mozglue/
|components=Core::mozglue
}}

{{Module
|name=mozilla-toplevel
|description=The top level directory for the mozilla tree.
|owner=[mailto:brendan@mozilla.org Brendan Eich]
|peers=
|group=
|source_dirs=tools/README
|url=
|components=
}}

{{Module
|name=MSCOM
|description=Integration with Microsoft Distributed COM
|owner=[mailto:aklotz@mozilla.com Aaron Klotz]
|peers=[mailto:jmathies@mozilla.com Jim Mathies]
|group=dev-platform
|source_dirs=ipc/mscom/%
|url=
|components=Core::IPC: MSCOM}}

{{Module
|name=Necko
|description=The Mozilla Networking Library
|owner=[mailto:mcmanus@ducksong.com Patrick McManus]
|peers= [mailto:jduell.mcbugs@gmail.com Jason Duell], [mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:mnovotny@mozilla.com Michal Novotny], [mailto:hurley@mozilla.com Nick Hurley], [mailto:dd.mozilla@gmail.com Dragana Damjanovic ],[mailto:valentin.gosu@gmail.com Valentin Gosu],[mailto:daniel@haxx.se Daniel Stenberg ], [mailto:schien@mozilla.com ShihChiang Chien]
|peersemeritus= [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sworkman@mozilla.com Steve Workman], [mailto:bzbarsky@mit.edu Boris Zbarsky]
|group=dev-tech-network
|source_dirs=netwerk/%, netwerk/base/, netwerk/build/, netwerk/cache/, netwerk/dns/, netwerk/locales/, netwerk/mime/, netwerk/protocol/, netwerk/resources/, netwerk/socket/, netwerk/streamconv/, netwerk/system/, netwerk/test/, netwerk/testserver/
|url=http://www.mozilla.org/projects/netlib/, https://developer.mozilla.org/en/Necko
|components=Core::Networking, Core::Networking: Cache, Core::Networking: Cookies, Core::Networking: FTP, Core::Networking: File, Core::Networking: HTTP, Core::Networking: JAR, Core::Networking: Websockets
}}

{{Module
|name=NSPR
|description=Netscape Portable Runtime
|owner=[mailto:kaie@kuix.de Kai Engert]
|peers=[mailto:wtc@google.com Wan-Teh Chang], [mailto:mh@glandium.org Mike Hommey]
|group=dev-tech-nspr
|source_dirs=nsprpub/
|url=http://www.mozilla.org/projects/nspr/
http://www.mozilla.org/projects/nspr/reference/html/
http://www.mozilla.org/projects/nspr/release-notes/
|components=NSPR
}}

{{Module
|name=PDF
|description=Rendering code to display documents encoded in the ISO 32000-1 `PDF' format.
|owner=Chris Jones, Andreas Gal
|peers=[mailto:aadib@mozilla.com Artur Adib], [mailto:bdahl@mozilla.com Brendan Dahl], [mailto:vnicolas@mozilla.com Vivien Nicolas]
|group=dev-platform
|source_dirs=media/pdf/
|url=https://github.com/mozilla/pdf.js
|components=Core::PDF
}}

{{Module
|name=Plugins
|description= NPAPI Plugin support.
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:joshmoz@gmail.com Josh Aas]
|peersemeritus=[mailto:john@pointysoftware.net John Schoenick], [mailto:robert@ocallahan.org Robert O'Callahan], [mailto:jstenback@gmail.com Johnny Stenback], Benjamin Smedberg
|group=
|source_dirs=dom/plugins/, modules/plugin/
|url=https://wiki.mozilla.org/Plugins
|components=Core::Plug-ins
}}

{{Module
|name=Preferences
|description=Preference library
|owner=[mailto:nnethercote@mozilla.com Nicholas Nethercote]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd], [mailto:felipe@mozilla.com Felipe Gomes], [mailto:glandium@mozilla.com Mike Hommey], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-platform
|source_dirs=modules/libpref/
|url=
|components=Core::Preferences: Backend
}}

{{Module
|name=Private Browsing
|description=Implementation of the Private Browsing mode, and the integration of other modules with Private Browsing APIs.
|owner=[mailto:josh@joshmatthews.net Josh Matthews] (while Ehsan is away)
|peers=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=Implementation and consumers of Private Browsing APIs in nsILoadContext, nsIPrivateBrowsingChannel, PrivateBrowsingUtils.jsm and the related glue code.
|url=https://wiki.mozilla.org/Private_Browsing
|components=Firefox::Private Browsing
}}

{{Module
|name=Privilege Manager
|description="caps"
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peersemeritus=[mailto:brendan@mozilla.org Brendan Eich], [mailto:jstenback@gmail.com Johnny Stenback], [mailto:dveditz@mozilla.com Dan Veditz]
|group=dev-tech-dom
|source_dirs=caps/
|url=http://www.mozilla.org/projects/security/components/index.html
|components=Core::Security: CAPS
}}

{{Module
|name=Push Notifications
|description=Push is a way for application developers to send messages to their web applications.
|owners=
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:nsm.nikhil@gmail.com Nikhil Marathe], [mailto:kcambridge@mozilla.com Kit Cambridge], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:ddamjanovic@mozilla.com Dragana Damjanovic]
|group=
|source_dirs=dom/push, dom/simplepush
|url=
|components=
}}

{{Module
|name=PyXPCOM
|description=The Python to XPCOM bridge.
|owner=Todd Whiteman
|peers=[mailto:mhammond@skippinet.com.au Mark Hammond]
|group=
|source_dirs=extension/python
|url=https://developer.mozilla.org/en/PyXPCOM
|components=
}}

{{Module
|name=RDF
|description=
|owner=[mailto:axel@pike.org Axel Hecht]
|peers=
|group=dev-tech-rdf
|source_dirs=rdf/
|url=http://www.mozilla.org/rdf/doc/
|components=Core::RDF
}}

{{Module
|name=security
|description=Crypto/PKI code, including NSS (Network Security Services) and JSS (NSS for Java)
|owner=[mailto:rrelyea@redhat.com Bob Relyea], [mailto:ttaubert@mozilla.com Tim Taubert]
|peers=[mailto:emaldona@redhat.com Elio Maldonado], [mailto:kaie@kuix.de Kai Engert], [mailto:ryan.sleevi@gmail.com Ryan Sleevi], [mailto:ekr@rtfm.com Eric Rescorla], [mailto:franziskuskiefer@gmail.com Franziskus Kiefer], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:wtc@google.com Wan-Teh Chang]
|group=dev-tech-crypto
|source_dirs=dbm/, security/coreconf/, security/dbm/, security/jss/, security/nss/, security/tinderbox/, security/tinderlight/
|url=http://mozilla.org/projects/security/pki/
|components=NSS, JSS, Core::Security, Core::Security: S/MIME
}}

{{Module
|name=Security - Mozilla PSM Glue
|description=Personal Security Manager
|owner=[mailto:dkeeler@mozilla.com David Keeler]
|peers=[mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:cykesiopka.bmo@gmail.com Cykesiopka]
|group=dev-tech-crypto
|source_dirs=security/manager/
|url=
|components=Core::Security: PSM, Core::Security: UI
}}

{{Module
|name=Static analysis & rewriting for C++
|description=Tools for checking C++ code looking for problems at compile time, plus tools for automated rewriting of C++ code.
|owner=[mailto:nika@thelayzells.com Nika Layzell] (while Ehsan is away)
|peers=[mailto:sfink@mozilla.com Steve Fink], [mailto:jrmuizel@mozilla.com Jeff Muizelaar], [mailto:birunthan@mohanathas.com Birunthan Mohanathas], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=build/clang-plugin, tools/rewriting among other out of tree tools
|url=
|components=Core::Rewriting & Analysis
}}
{{Module
|name=storage
|description=Storage APIs with a SQLite backend
|owner=[mailto:mak77@bonardo.net Marco Bonardo]
|peers=[mailto:bugmail@asutherland.org Andrew Sutherland], [mailto:jvarga@mozilla.com Jan Varga]
|group=dev-platform
|source_dirs=db/sqlite3/, storage/
|url=http://developer.mozilla.org/en/docs/Storage
|components=Toolkit::Storage, Core::SQL
}}

{{Module
|name=String
|description=
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[https://mozillians.org/en-US/u/froydnj/ Nathan Froyd], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-tech-xpcom
|source_dirs=string/, xpcom/string/
|url=https://developer.mozilla.org/En/Mozilla_internal_string_guide
|components=Core::String
}}

{{Module
|name=Style System
|description=CSS style sheet handling; style data computation
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:cam@mcc.id.au Cameron McCormack]
|group=dev-tech-layout
|source_dirs=layout/style/
|url=https://wiki.mozilla.org/Gecko:Overview#Style_System
|components=Core::CSS Parsing and Computation
}}

{{Module
|name=SVG
|description=Scalable Vector Graphics
|owner=[mailto:jwatt@jwatt.org Jonathan Watt]
|peers=[mailto:longsonr@gmail.com Robert Longson], [mailto:robert@ocallahan.org Robert O'Callahan], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:birtles@gmail.com Brian Birtles]
|group=dev-tech-svg
|source_dirs=dom/svg/, layout/svg/, dom/smil/
|url=https://developer.mozilla.org/en-US/docs/Web/SVG
|components=Core::SVG
}}

{{Module
|name=Tamarin
|description=VM for ActionScript and JavaScript
|owner=Edwin Smith, [mailto:jodyer@adobe.com Jeff Dyer]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:stejohns@adobe.com Steven Johnson], [mailto:tierney@adobe.com Erik Tierney], [mailto:treilly@adobe.com Tom Reilly]
|group=dev-tech-js-engine
|source_dirs=js/tamarin
|url=http://www.mozilla.org/projects/tamarin/
http://wiki.mozilla.org/tamarin/
http://hg.mozilla.org/tamarin-central/
http://hg.mozilla.org/tamarin-tracing/
|components=Tamarin
}}

{{Module
|name=Test Harness
|description=In-tree test infrastructure and tools. Harnesses include, XPCShell, Mochitest (& Chrome), Reftest, JsREftest, Compiled Code Tests, Robocop, Mozmill, Marionette, Firefox UI Tests. Requests for new harnesses should go to Testing::General.
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:dbaron@dbaron.org David Baron] (reftest), [mailto:jwalden@mit.edu Jeff Walden] (httpd.js, jsreftest), Rob Campbell (mochitest, mochitest chrome, marionette), [mailto:jmaher@mozilla.com Joel Maher] (reftest, mochitest, jsreftest), [mailto:ctalbert@mozilla.com Clint Talbert] (reftest, compiled code, mozmill), [mailto:geoffbrown@mozilla.com Geoff Brown] (robocop), [mailto:hskupin@mozilla.com Henrik Skupin] (Marionette, Firefox UI tests), [mailto:ato@mozilla.com Andreas Tolfsen] (marionette), [mailto:jgriffin Jonathan Griffin] (marionette), [mailto:dburns@mozilla.com David Burns] (marionette), [mailto:dminor@mozilla.com Dan Minor], [mailto:mjzffr@gmail.com Maja Frydrychowicz] (Marionette, Firefox UI tests),

|group=dev-quality
|source_dirs=/testing
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::General, Testing::Mochitest, Testing::Mochitest Chrome, Testing::Marionette, Testing::Mozmill, Testing::Reftest, Testing::XPCShell Harness, Testing::httpd.js
}}

{{Module
|name=Testing Infrastructure
|description=Testing tools and infrastructure for Mozilla projects, harnesses for automated tests, stand-alone test tools. Talos, Graph Server, Mozbase, Pulse, WOO, Bughunter, SUTAgent, Eideticker
|owner=[mailto:jmaher@mozilla.com Joel Maher]
|peers=[mailto:bclary@bclary.com Bob Clary], [mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:ccooper@deadsquid.com Chris Cooper], [mailto:ctalbert@mozilla.com Clint Talbert], [mailto:robert@roberthelmer.com Robert Helmer], [mailto:jmaher@mozilla.com Joel Maher], Rob Campbell, [mailto:wlach@mozilla.com William Lachance], [mailto:jeads@mozilla.com Jonathan Eads], [mailto:jgriffin Jonathan Griffin], [mailto:bmoss@mozilla.com Bob Moss], [mailto:mcote@mozilla.com Mark Côté]
|group=dev-quality
|source_dirs=testing/, tools/httptester/, tools/page-loader/, tools/test-harness/, tools/tests/, tools/testserver/, tools/testy/
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::Infrastructure
}}

{{Module
|name=JS Marionette
|description=NodeJS test harness, marionette client, and other utilities for running marionette tests (submodule of Test Infrastructure)
|owner=[mailto:jlal@mozilla.com James Lal] <lightsofapollo>, [mailto:gaye@mozilla.com Gareth Aye] <gaye>
|peers=[mailto:aus@mozilla.com Ghislain "Aus" Lacroix] <auswerk>
|source_dirs=gaia/tests/jsmarionette
|components=Testing::JSMarionette
|group=dev-gaia
}}

{{Module
|name=XPCShell Test Harness
|description=The XPCShell Harness
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:jmaher@mozilla.com Joel Maher]
|source_dirs=testing/xpcshell
|components=Testing::XPCShell Harness
}}

{{Module
|name=Update Service
|description=server code for Mozilla Update services (aus, addons, pfs)
|owner=Mike Morgan
|peers=[mailto:jscott@mozilla.com Justin Scott], [mailto:shaver@mozilla.org Mike Shaver], [mailto:wclouser@mozilla.com Will Clouser]
|group=dev-amo
|source_dirs=webtools/addons/, webtools/aus/, webtools/update/
|url=http://wiki.mozilla.org/wiki/AMO
|components=AUS::Administration, AUS::Systems
}}

{{Module
|name=View System
|description=The View Manager is responsible for handling "heavyweight" rendering (some clipping, compositing) and event handling tasks.
|owner=[mailto:mstange@themasta.com Markus Stange]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dbaron@dbaron.org David Baron]
|group=dev-tech-layout
|source_dirs=view/
|url=
|components=Core::Layout: View Rendering
}}

{{Module
|name=Web Audio
|description=Support for the W3C Web Audio API specification.
|owner=[mailto:padenot@mozilla.com Paul Adenot]
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:karlt+@karlt.net Karl Tomlinson]
|group=dev-platform
|source_dirs=dom/media/webaudio
|url=https://wiki.mozilla.org/Web_Audio_API
|components=Core::Web Audio
}}

{{Module
|name=Web Painting
|description=painting, display lists, and layer construction
|owner=[mailto:matt.woodrow@gmail.com Matt Woodrow]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:dbaron@dbaron.org David Baron], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:mstange@themasta.com Markus Stange]
|group=dev-tech-layout
|source_dirs= layout/painting, the display list and layer related methods on nsIFrame and its subclasses
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout: Web Painting
}}

{{Module
|name=WebRTC
|description=WebRTC is responsible for realtime audio and video communication, as well as related issues like low-level camera and microphone access
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:bcampen@mozilla.com Byron Campen] [mailto:abr@mozilla.com Adam Roach]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=netwerk/sctp (also see submodules "WebRTC Media" and "WebRTC Signaling")
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC, Core::WebRTC Networking
}}

{{Module
|name=WebVR
|description=Gecko's implementation of WebVR (Virtual Reality) functionality, including API, devices, graphics and integration
|owner=[mailto:kgilbert@mozilla.com Kip Gilbert]
|peers=[mailto:dmu@mozilla.com Daosheng Mu]
|peersemeritus=[mailto:vladimir@pobox.com Vladimir Vukicevic]
|group=dev-platform
|source_dirs=dom/vr, gfx/vr
|url=https://mozvr.com/
|components=Core::WebVR
}}

{{Module
|name=Widget
|description=
|owner=[mailto:vladimir@pobox.com Vladimir Vukicevic]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peersemeritus=[mailto:pavlov@pavlov.net Stuart Parmenter],
|group=dev-platform
|source_dirs=widget/, widget/xpwidgets/
|url=
|components=Core::Drag and Drop, Core::Widget, Core::Printing: Setup
}}

{{Module
|name=Widget - Android
|description=The Android Port
|owner=[mailto:blassey.bugs@lassey.us Brad Lassey]
|peers=[mailto:jwillcox@mozilla.com James Willcox]
|group=dev-platforms-mobile
|source_dirs=widget/android/, embedding/android
|url=
|components=Core::Widget: Android
}}

{{Module
|name=Widget - GTK
|description=supported X widgetry and gfx
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|group=dev-platform
|source_dirs=widget/gtk/, widget/gtk2/, widget/gtksuperwin/, widget/gtkxtbin/
|url=http://www.mozilla.org/unix/, http://www.gtk.org, http://www.mozilla.org/ports/gtk/
|components=Core::Widget: Gtk
}}

{{Module
|name=Widget - OS X
|description= Gecko's OS X compatibility layer.
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:joshmoz@gmail.com Josh Aas], [mailto:bgirard@mozilla.com Benoit Girard], [mailto:spohl@mozilla.com Stephen Pohl], [mailto:smichaud@pobox.com Steven Michaud]
|group=dev-platform
|source_dirs=widget/cocoa/
|url=
|components=Core::Widget: Cocoa
}}

{{Module
|name=Widget - Windows
|description=Windows widgets and desktop integration
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook], [mailto:vladimir@pobox.com Vladimir Vukicevic], [mailto:jmathies@mozilla.com Jim Mathies]
|peersemeritus=[mailto:blassey@mozilla.com Brad Lassey], [mailto:netzen@gmail.com Brian Bondy], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:doug.turner@gmail.com Doug Turner], [mailto:timeless@mozdev.org Josh 'timeless' Soref], [mailto:robarnold@cmu.edu Rob Arnold]
|group=dev-platform
|source_dirs=widget/windows/
|url=
|components=Core::Widget: Win32
}}

{{Module
|name=XBL
|description=eXtensible Binding Language
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:jonas@sicking.cc Jonas Sicking]
|ownersemeritus=[mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xbl
|source_dirs=dom/xbl/
|url=http://www.mozilla.org/projects/xbl/
|components=Core::XBL
}}

{{Module
|name=XML
|description=XML in Mozilla, including XML, XHTML, Namespaces in XML, Associating Style Sheets with XML Documents, XML Linking and XML Extras. XML-related things that are not covered by more specific projects.
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-tech-xml
|source_dirs=dom/xml/, extensions/xmlextras/, parser/expat/
|url=http://www.mozilla.org/newlayout/xml/
|components=Core::XML
}}

{{Module
|name=XPApps
|description=Cross-Platform Applications, mostly Navigator front end and application shell.
|owner=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|peers=[mailto:dean_tessman@hotmail.com Dean Tessman], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-apps-seamonkey
|source_dirs=xpfe/
|url=http://www.mozilla.org/xpapps/
|components=
}}

{{Module
|name=XPCOM
|description=The cross-platform object model and core data structures.
|owner=[https://mozillians.org/en-US/u/froydnj/ Nathan Froyd]
|peers=[mailto:erahm@mozilla.com Eric Rahm]
|ownersemeritus=Benjamin Smedberg
|peersemeritus=[https://mozillians.org/en-US/u/dougt/ Doug Turner]
|group=dev-platform
|source_dirs=startupcache/, xpcom/%, xpcom/base/, xpcom/build/, xpcom/components/, xpcom/ds/, xpcom/glue/, xpcom/proxy/, xpcom/sample/, xpcom/stub/, xpcom/tests/, xpcom/threads/, xpcom/tools/, xpcom/windbgdlg/
|url=http://developer.mozilla.org/en/XPCOM
|components=Core::XPCOM
}}

{{Module
|name=XPConnect
|description=Deep Magic
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:gkrizsanits@mozilla.com Gabor Krizsanits], [mailto:amccreight@mozilla.com Andrew McCreight], [mailto:kmaglione@mozilla.com Kris Maglione]
|peersemeritus=[mailto:gal@uci.edu Andreas Gal], [mailto:jstenback@gmail.com Johnny Stenback]
|group=
|source_dirs=js/xpconnect/
|url=
|components=Core::XPConnect
}}

{{Module
|name=XPIDL
|description=Cross-platform IDL compiler; produces .h C++ header files and .xpt runtime type description files from .idl interface description files.
|owner=[mailto:me@kylehuey.com Kyle Huey]
|peersemeritus=[mailto:shaver@mozilla.org Mike Shaver], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-tech-xpcom
|source_dirs=xpcom/typelib/
|url=http://www.mozilla.org/scriptable/xpidl
http://www.mozilla.org/scriptable
|components=
}}

{{Module
|name=XPInstall
|description=
|owner=[mailto:dveditz@mozilla.com Dan Veditz]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|group=dev-tech-xpinstall
|source_dirs=xpinstall/
|url=
|components=Core::Installer: XPInstall Engine
}}

{{Module
|name=XPToolkit
|description=Cross-platform user interface toolkit
|owner=
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:Jan.Varga@gmail.com Jan Varga]
|group=dev-tech-xul
|source_dirs=dom/xul/, layout/xul/
|url=http://www.mozilla.org/xpfe/
|components=Core::XP Toolkit/Widgets: Menus, Core::XP Toolkit/Widgets: XUL
}}

{{Module
|name=XSLT Processor
|description=XSLT transformations processor
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:axel@pike.org Axel Hecht], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xslt
|source_dirs=dom/xslt/
|url=http://www.mozilla.org/projects/xslt/, http://www.w3.org/TR/xslt.html
|components=Core::XSLT
}}

{{Module
|name=Sandboxing
|description=Cross platform sandboxing
|owner=[mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|peers=[mailto:bowen@mozilla.com Bob Owen], [mailto:aklotz@mozilla.com Aaron Klotz], [https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes], [mailto:gDestuynder@mozilla.com Guillaume Destuynder], [mailto:jld@mozilla.com Jed Davis]
|group=dev-platform
|source_dirs=security/sandbox
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Windows
|description=Sandboxing for the Windows platform
|owner=[mailto:bowen@mozilla.com Bob Owen]
|peers=[mailto:netzen@gmail.com Brian Bondy], [mailto:aklotz@mozilla.com Aaron Klotz], [https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes], [mailto:jimm@mozilla.com Jim Mathies]
|group=dev-platform
|source_dirs=security/sandbox/win
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - OSX
|description=Sandboxing for the OSX platform
|owner=[mailto:haftandilian@mozilla.com Haik Aftandilian]
|peers=
|group=dev-platform
|source_dirs=security/sandbox/mac
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Linux & B2G
|description=Sandboxing for the Linux & B2G platforms
|owner=[mailto:jhector@mozilla.com Julian Hector]
|peers=[mailto:jld@mozilla.com Jed Davis] [mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|group=dev-platform
|source_dirs=security/sandbox/linux
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

===Submodules===
{{Module
|name=Build Config - Fennec
|description=Submodule of the build config covering Fennec's build system in mobile/android.
|owner=[mailto:nalexander@mozilla.com Nicholas Alexander]
|peers=Same as Build Config
|group=dev-builds
|components=Core::Build Config
}}

{{Module
|name=WebRTC Media
|description=Submodule of WebRTC responsible for access to media input devices (microphones, cameras, screen capture), as well as realtime audiovisual codecs and packetization.
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:jib@mozilla.com Jan-Ivar Bruaroey], [mailto:dminor@mozilla.com Dan Minor], [mailto:apehrson@mozilla.com Andreas Pehrson],
|peersemeritus=[mailto:pkerr@mozilla.com Paul Kerr], [mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=/media/webrtc, /dom/media/webrtc, /dom/media/systemservices
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Audio/Video)
}}

{{Module
|name=WebRTC Signaling
|description=Submodule of WebRTC responsible for implementation of PeerConnection API, WebRTC identity, and SDP/JSEP handling
|owner=[mailto:bcampen@mozilla.com Byron Campen]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:abr@mozilla.com Adam Roach], [mailto:rjesup@mozilla.com Randell Jesup], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=/media/webrtc/signaling/
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Signaling)
}}

<noinclude>

===Unassigned Bugzilla Components===

The following Bugzilla components in the Core project have not been assigned to a module (this list is not exhaustive):

<pre>
Core::File Handling
Core::Find Backend
Core::Gecko Profiler
Core::General
Core::HTML: Form Submission
Core::History: Global
Core::Image Blocking
Core::JavaScript Debugging APIs
Core::Localization
Core::Nanojit
Core::Networking: Domain Lists
Core::Print Preview
Core::Printing: Output
Core::Printing: Setup
Core::Profile: BackEnd
Core::Profile: Migration
Core::Profile: Roaming
Core::QuickLaunch (AKA turbo mode)
Core::Rewriting and Analysis
Core::Selection
Core::Serializers
Core::Spelling checker
Core::Tracking
Core::Web Services
Core::WebDAV
Core::Widget: OS/2
Core::Widget: Photon
Core::X-remote
Core::XForms
Core::XUL
</pre>
</noinclude>

Modules/Core

2017-11-28T13:22:33Z

Surkov.alexander:

<noinclude>
'''Only module owners may edit this page.'''

They may:

* update any information about their module except the name of the owner
* add or remove sub-modules
* change the owner of a sub-module
* add emeritus owners or peers

Other changes, including changes of module owner or addition/removal of modules, must be agreed with the Module Ownership Module group, probably via a discussion in [https://www.mozilla.org/about/forums/#governance mozilla.governance].
</noinclude>
{{Module
|name=Accessibility
|description=Support for platform accessibility APIs. Accessibility APIs are used by 3rd party software like screen readers, screen magnifiers, and voice dictation software, which need information about document content and UI controls, as well as important events like changes of focus.
|owner=[mailto:surkov.alexander@gmail.com Alexander Surkov]
|peers=[mailto:dbolter@mozilla.com David Bolter], [mailto:eitan@monotonous.org Eitan Isaacson],[mailto:jteh@mozilla.com James Teh], [mailto:mzehe@mozilla.com Marco Zehe], [mailto:yzenevich@mozilla.com Yura Zenevich]
|ownersemeritus=[mailto:aaron@moonset.net. Aaron Leventhal]
|peersemeritus=[mailto:tbsaunde+mozbugs@tbsaunde.org Trevor Saunders], [mailto:ginn.chen@oracle.com Ginn Chen], Evan Yan
|group=dev-accessibility
|source_dirs=accessible/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=Browser WebAPI
|description=Web API for rendering apps, browser windows and widgets.
|owner=[mailto:kchen@mozilla.com Kan-Ru Chen]
|peers=[mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:fabrice@mozilla.com Fabrice Desré]
|group=dev-webapi
|source_dirs=dom/browser-element/
|url=
|components=Core::DOM
}}

{{Module
|name=Build and Release Tools
|description=Tools related to build and release automation and configuration of release builds.
|owner=[mailto:nthomas@mozilla.com Nick Thomas]
|peers=[mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:coop@mozilla.com Chris Cooper]
|group=release-engineering
|source_dirs=browser/config/mozconfigs/, mobile/android/config/mozconfigs/, xulrunner/config/mozconfigs/, b2g/config/, tools/update-packaging/
|url=https://wiki.mozilla.org/ReleaseEngineering
|components=Release Engineering::*
}}

{{Module
|name=Build Config
|description=The build system for Gecko and several mozilla.org hosted Gecko-based applications.
|owner=[mailto:gps@mozilla.com Gregory Szorc] (:gps)
|peers=[mailto:mh@glandium.org Mike Hommey] (:glandium), [mailto:mshal@mozilla.com Mike Shal] (:mshal), [mailto:ted@mielczarek.org Ted Mielczarek] (:ted), [mailto:cmanchester@mozilla.com Chris Manchester](:chmanchester), [mailto:nfroyd@mozilla.com Nathan Froyd] (:froydnj), [mailto:rgiles@mozilla.com Ralph Giles] (:rillian)
|ownersemeritus=Ted Mielczarek (2008-[https://blog.mozilla.org/ted/2013/03/07/gregory-szorc-is-now-the-build-config-module-owner/ 2013]), Benjamin Smedberg (???-[http://benjamin.smedbergs.us/blog/2008-04-30/more-changing-of-the-guard-ted-mielczarek/ 2008]),
|group=dev-builds
|source_dirs=build/, config/, python/mozbuild, tools/cross-commit, tools/cvs2hg-import.py, tools/cvsmgmt/, tools/elf-dynstr-gc/, tools/trees.pl, browser/config/mozconfigs/, mobile/config/mozconfigs/, xulrunner/config/mozconfigs/
|url=http://www.mozilla.org/build/
|components=Core::Build Config
}}

{{Module
|name=Code Analysis and Debugging Tools
|description=Tools for debugging Mozilla code or for analyzing speed, memory use, and other characteristics of it.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=
|group=dev-performance
|source_dirs=tools/codesighs/, tools/debug/, tools/dreftool/, tools/dumpdeps/, tools/footprint/, tools/jprof/, tools/leaky/, tools/memory/, tools/module-deps/, tools/performance/, tools/post_compile/, tools/preloader/, tools/rb/, tools/reorder/, tools/trace-malloc/, tools/uuiddeps/,
|url=
|components=
}}

{{Module
|name=Content HTTP Headers
|description=HTTP headers related to content, e.g. User-Agent, Content-Type, Accept. (Transport-related headers are the responsibility of the Necko module owner.)
|owner=[mailto:gerv@mozilla.org Gervase Markham]
|peers=[mailto:lmandel@mozilla.com Lawrence Mandel]
|group=dev-platform
|source_dirs=
|url=https://developer.mozilla.org/en/Gecko_user_agent_string_reference
|components=Core::Networking: HTTP
}}

{{Module
|name=Content Security
|description=Native content-based security features, including: Content Security Policy (CSP), Mixed Content Blocker (MCB), Subresource Integrity (SRI) and CORS.
|owner=[mailto:ckerschbaumer@mozilla.com Christoph Kerschbaumer]
|peers=[mailto:francois@mozilla.com François Marier], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:tvyas@mozilla.com Tanvi Vyas], [mailto:dveditz@mozilla.com Dan Veditz], [mailto:mozilla@sidstamm.com Sid Stamm]
|group=dev-security
|source_dirs=dom/security
|components=Core::DOM: Security
}}

{{Module
|name=Cookies and Permissions
|description=
|owner=Monica Chew
|peers=[mailto:josh@joshmatthews.com Josh Matthews], [mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:mconnor@steelgryphon.com Mike Connor], [mailto:dwitte@gmail.com Dan Witte], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sdwilsh@shawnwilsher.com Shawn Wilsher (ping on irc)]
|group=dev-tech-network
|source_dirs=extensions/cookie/, netwerk/cookie/
|url=
|components=Core::Networking: Cookies
}}
{{Module
|name=Cycle Collector
|description=Code to break and collect objects within reference cycles
|owner=[https://mozillians.org/en-US/u/mccr8/ Andrew McCreight]
|peers=Peter Van der Beken, Olli Pettay, David Baron
|source_dirs=xpcom/base/nsCycleCollector.* and some support headers
|components=Core::XPCOM
|group=dev-platform
}}
{{Module
|name=C++/Rust usage, tools, and style
|description=Aspects of C++ use such as language feature usage, standard library versions/usage, compiler/toolchain versions, formatting and naming style, and aspects of Rust use as needs arise
|owner=[mailto:nfroyd@mozilla.com Nathan Froyd] (while Ehsan is away)
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:glandium@mozilla.com Mike Hommey], [mailto:jwalden@mozilla.com Jeff Walden], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|source_dirs=non-third-party C++ and Rust code in the tree
|components=Various components
|group=dev-platform
}}
{{Module
|name=docshell
|description=
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:sawang@mozilla.com Samael Wang]
|peersemeritus=[mailto:jstenback@gmail.com Johnny Stenback],[mailto:cbiesinger@gmail.com Christian Biesinger],[mailto:justin.lebar@gmail.com Justin Lebar]
|group=dev-platform
|source_dirs=docshell/, uriloader/
|url=
|components=Core::Document Navigation
}}

{{Module
|name=Document Object Model
|description=
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:hsivonen@iki.fi Henri Sivonen], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:baku@mozilla.com Andrea Marchesini],
[mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:bkelly@mozilla.com Ben Kelly], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:kyle@nonpolynomial.com Kyle Machulis]
|ownersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|peersemeritus=[mailto:justin.lebar@gmail.com Justin Lebar], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:bent.mozilla@gmail.com Ben Turner], [mailto:mounir@lamouri.fr Mounir Lamouri (still active, but slower to respond than previously)], [mailto:me@kylehuey.com Kyle Huey]
|group=dev-tech-dom
|source_dirs=dom/*, except directories covered by other modules
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM, Core::DOM: CSS Object Model, Core::DOM: Core & HTML
}}

{{Module
|name=DOM File
|description=DOM Blob, File and FileSystem APIs
|owner=[mailto:amarchesini@Mozilla.com Andrea Marchesini]
|peers=[mailto:olli@pettay.fi Olli Pettay]
|group=dev-platform
|source_dirs=dom/file, dom/filesystem
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: File
}}

{{Module
|name=Event Handling
|description=DOM Events and Event Handling
|owner=[mailto:olli@pettay.fi Olli Pettay], [mailto:masayuki@d-toybox.com Masayuki Nakano]
|peers=[mailto:sshih@mozilla.com Stone Shih]
|group=dev-platform
|source_dirs=dom/events and event handling related code elsewhere
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: Events, Core::Event Handling
}}

{{Module
|name=Web Workers
|description=
|owner=[mailto:baku@mozilla.com Andrea Marchesini]
|peers=[mailto:mrbkap@mozilla.com Blake Kaplan], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey], [mailto:bkelly@mozilla.com Ben Kelly]
|ownersemeritus=[mailto:bent.mozilla@gmail.com Ben Turner]
|group=dev-platform
|source_dirs=dom/workers/
|url=https://developer.mozilla.org/En/Using_web_workers
|components=Core::DOM: Workers
}}

{{Module
|name=IndexedDB
|description=
|owner=[mailto:jvarga@mozilla.com Jan Varga]
|peers=[mailto:btseng@mozilla.com Bevis Tseng], [mailto:bugmail@asutherland.org Andrew Sutherland], [mailto:baku@mozilla.com Andrea Marchesini]
|ownersemeritus=[mailto:bent.mozilla@gmail.com Ben Turner]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey]
|group=dev-platform
|source_dirs=dom/indexedDB/
|url=https://developer.mozilla.org/en/IndexedDB
|components=Core::DOM: IndexedDB
}}

{{Module
|name=Editor
|description=
|owner=[mailto:masayuki@d-toybox.com Masayuki Nakano]
|peers=
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=editor/
|url=http://www.mozilla.org/editor/
|components=Core::Editor
}}

{{Module
|name=Embedding
|description=Gecko embedding APIs and frameworks
|owner=[mailto:myk@mykzilla.org Myk Melez]
|ownersemeritus=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:bdahl@mozilla.com Brendan Dahl], [mailto:tbsaunde@tbsaunde.org Trevor Saunders]
|peersemeritus=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-platform
|source_dirs=embedding/
|url=
|components=Core::Embedding: APIs
}}

{{Module
|name=Find As You Type
|description=Find As You Type (formerly called Type Ahead Find) is a feature that allows quick web page navigation when you type a succession of characters in the body of the displayed page (not in an edit box of or drop down list). Currently seeks new owner.
|owner=
|peers=
|group=dev-accessibility
|source_dirs=extensions/typeaheadfind/
|url=http://www.mozilla.org/access/type-ahead/
|components=
}}

{{Module
|name=Gecko Profiler
|description=Gecko's built-in profiler
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:nnethercote@mozilla.com Nicholas Nethercote], [mailto:jseward@mozilla.com Julian Seward] (LUL), [mailto:kvijayan@mozilla.com Kannan Vijayan] (JS integration), [mailto:shu@mozilla.com Shu-yu Guo] (JS integration), [mailto:tlee@mozilla.com Thinker Lee] (TaskTracer), [mailto:cyu@mozilla.com Cervantes Yu] (TaskTracer), [mailto:b56girard@gmail.com Benoit Girard].
|group=dev-platform
|source_dirs=tools/profiler/
|url=https://developer.mozilla.org/en-US/docs/Mozilla/Performance/Profiling_with_the_Built-in_Profiler
|components=Core::Gecko Profiler
}}

{{Module
|name=Geolocation
|description=Implementation of the Geolocation W3C Spec, location provider apis, and wifi scanning code.
|owner=[mailto:josh@joshmatthews.net Josh Matthews], [mailto:kchen@mozilla.com Kan-Ru Chen]
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner], Garvan Keeley
|peers=
|group=dev-tech-dom
|source_dirs=dom/geolocation, dom/system/, netwerk/wifi
|url=https://developer.mozilla.org/En/Using_geolocation
|components=Core::Geolocation
}}

{{Module
|name=Global Key Bindings
|description=Global hot keys in Mozilla for the browser, editor, mail-news and widgets. Does not include underlined menu accelerators and the like, as those are part of i18n.
|owner=Aaron Leventhal
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|group=dev-accessibility
|source_dirs=dom/xbl/builtin/
|url=http://www.mozilla.org/projects/ui/accessibility/mozkeyintro.html
|components=Core::Keyboard: Navigation
}}

{{Module
|name=Graphics
|description=Mozilla graphics API
|owner=[mailto:jrmuizel@mozilla.com Jeff Muizelaar](Thebes, QCMS, YCbCr, Cairo/Pixman, Regions, OS X, Other)
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:jdrew@mozilla.com Joe Drew], [mailto:vladimir@pobox.com Vladimir Vukicevic], [mailto:bas.schouten@live.nl Bas Schouten](Layers, Windows), [mailto:bjacob@mozilla.com Benoit Jacob](gfx/gl), [mailto:bgirard@mozilla.com Benoit Girard](Compositor, Performance), [mailto:ajuma.bugzilla@alijuma.com Ali Juma], [mailto:jgilbert@mozilla.com Jeff Gilbert](WebGL, ANGLE), [mailto:george@mozilla.com George Wright](Canvas2D), [mailto:mwoodrow@mozilla.com Matt Woodrow](Layers API), [mailto:jdaggett@mozilla.com John Daggett](text/fonts), [mailto:jfkthame@googlemail.com Jonathan Kew](text/fonts), [mailto:nsilva@mozilla.com Nicolas Silva](MozSurface), [mailto:ncameron@mozilla.com Nick Cameron], [mailto:sikeda@mozilla.com Sotaro Ikeda](B2G), [mailto:snorp@mozilla.com James Willcox](Android), [mailto:clord@mozilla.com Christopher Lord], [mailto:mstange@themasta.com Markus Stange](OS X), [mailto:lsalzman@mozilla.com Lee Salzman](Skia), [mailto:mchang@mozilla.com Mason Chang], [mailto:dvander@mozilla.com David Anderson]
|group=dev-platform
|source_dirs=gfx/, dom/canvas/
|url=https://wiki.mozilla.org/Platform/GFX https://wiki.mozilla.org/Gecko:Layers https://wiki.mozilla.org/Gecko:2DGraphicsSketch
|components=Core::Graphics, Core::Graphics: Layers, Core::Graphics: Text, Core::GFX: Color Management, Core::Canvas: 2D, Core::Canvas: WebGL
}}

{{Module
|name=APZ (Graphics submodule)
|description=Asynchronous panning and zooming
|owner=[mailto:kgupta@mozilla.com Kartikaya Gupta]
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:tnikkel@mozilla.com Timothy Nikkel], [mailto:dvander@mozilla.com David Anderson], [mailto:mstange@mozilla.com Markus Stange]
|group=dev-platform
|source=gfx/layers/apz
|url=https://wiki.mozilla.org/Platform/GFX/APZ
|components=Core::Panning and Zooming
}}

{{Module
|name=Moz2D (Graphics submodule)
|description=Platform independent 2D graphics API
|owner=[mailto:bschouten@mozilla.com Bas Schouten]
|peers=[mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:gwright@mozilla.com George Wright], [mailto:jwatt@jwatt.org Jonathan Watt]
|group=dev-platform
|source=gfx/2d
|url=https://wiki.mozilla.org/Platform/GFX/Moz2D
|components=Core::Graphics
}}

{{Module
|name=Legacy HTML Parser
|description=
|owner=[mailto:mrbkap@gmail.com Blake Kaplan]
|peers=[mailto:dbaron@dbaron.org David Baron], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:rbs@maths.uq.edu.au rbs@maths.uq.edu.au]
|peersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|source_dirs=parser/htmlparser
|url=http://www.mozilla.org/newlayout/doc/parser.html
|components=Core::HTML: Parser
}}

{{Module
|name=HAL
|description=Hardware Abstraction Layer
|owner=[https://mozillians.org/u/dhylands/ Dave Hylands]
|peers=[mailto:gsvelto@mozilla.com Gabriele Svelto]
|group=dev-platform
|source_dirs=hal/
|components=Core::Hardware Abstraction Layer (HAL)
}}

{{Module
|name=HTML Parser
|description=The HTML Parser transforms HTML source code into a DOM. It conforms to the HTML specification, and is mostly translated automatically from Java to C++.
|owner=[mailto:hsivonen@iki.fi Henri Sivonen]
|peers=[mailto:wchen@mozilla.com William Chen]
|group=dev-platform
|source_dirs=parser/html
|url=http://about.validator.nu/
|components=Core::HTML: Parser
}}

{{Module
|name=I18N Library
|description=
|owner=[mailto:jshin1987@gmail.com Jungshik Shin], [mailto:smontagu@smontagu.org Simon Montagu]
|peers=[mailto:VYV03354@nifty.ne.jp Masatoshi Kimura]
|group=dev-i18n
|source_dirs=intl/
|url=http://mozilla.org/projects/intl/index.html
|components=Core::Internationalization
}}

{{Module
|name=ImageLib
|description=
|owner=[mailto:tnikkel@gmail.com Timothy Nikkel]
|peers=[mailto:aosmond@mozilla.com Andrew Osmond], [mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:seth.bugzilla@blackhail.net Seth Fowler]
|peersemeritus=[mailto:netzen@gmail.com Brian Bondy], [mailto:justin.lebar@gmail.com Justin Lebar]
|group=dev-platform
|source_dirs=media/libjpeg/, media/libpng/, image/, modules/zlib/
|url=
|components=Core::ImageLib
}}

{{Module
|name=IPC
|description=Message-passing between threads and processes
|owner=[mailto:wmccloskey@mozilla.com Bill McCloskey]
|peers=[mailto:danderson@mozilla.com David Anderson], [mailto:kchen@mozilla.com Kan-Ru Chen], [mailto:jld@mozilla.com Jed Davis], [mailto:nfroyd@mozilla.com Nathan Froyd], [mailto:bkelly@mozilla.com Ben Kelly], [mailto:amccreight@mozilla.com Andrew McCreight]
|group=dev-platform
|source_dirs=ipc/glue/, ipc/ipdl/, ipc/chromium/
|url=
|components=Core::IPC}}

{{Module
|name=JavaScript
|description=JavaScript engine (SpiderMonkey)
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:jdemooij@mozilla.com Jan de Mooij], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:nnethercote@mozilla.com Nick Nethercote], [mailto:jwalden@mit.edu Jeff Walden], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:evilpies@gmail.com Tom Schuster], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:till@tillschneidereit.net Till Schneidereit], [mailto:efaust@mozilla.com Eric Faust], [mailto:nfitzgerald@mozilla.com Nick Fitzgerald], [mailto:luke@mozilla.com Luke Wagner], [mailto:arai.unmht@gmail.com Tooru Fujisawa], [mailto:sunfish@mozilla.com Dan Gohman], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:nmatsakis@mozilla.com Niko Matsakis], [mailto:ejpbruel@mozilla.com Eddy Bruel], [mailto:danderson@mozilla.com David Anderson], [mailto:igor@mir2.org Igor Bukanov], [mailto:brendan@mozilla.org Brendan Eich], Andreas Gal
|group=dev-tech-js-engine
|source_dirs=js/src
|url=http://www.mozilla.org/js/spidermonkey,
http://developer.mozilla.org/en/docs/About_JavaScript
|components=Core::JavaScript Engine
}}

{{Module
|name=JavaScript JIT
|description=JavaScript engine's JIT compilers (IonMonkey, Baseline)
|owner=[mailto:jdemooij@mozilla.com Jan de Mooij]
|peers=[mailto:danderson@mozilla.com David Anderson], [mailto:bbouvier@mozilla.com Benjamin Bouvier], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:nicolas.b.pierron@mozilla.com Nicolas Pierron], [mailto:evilpies@gmail.com Tom Schuster], [mailto:sstangl@mozilla.com Sean Stangl], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:luke@mozilla.com Luke Wagner]
|group=dev-tech-js-engine-internals
|source_dirs=js/src/jit
|url=http://www.mozilla.org/js/spidermonkey
|components=Core::JavaScript Engine: JIT
}}

{{Module
|name=JavaScript Debugger Backend
|description=JavaScript debugging hooks
|owner=[mailto:timeless@mozdev.org Josh 'timeless' Soref]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:rginda@hacksrus.com Rob Ginda]
|group=dev-apps-js-debugger
|source_dirs=js/jsd/
|url=http://www.mozilla.org/js/jsd
|components=Other Applications::Venkman JS Debugger
}}

{{Module
|name=jsat
|description=Javascript screen reader that is used in Android and B2G
|owner=[mailto:eitan@monotonous.org Eitan Isaacson]
|peers=[mailto:yzenevich@mozilla.com Yura Zenevich]
|group=dev-accessibility
|source_dirs=accessible/jsat/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=js-ctypes
|description=A foreign function interface which allows privileged JS code to interact with binary code without using XPCOM/XPConnect.
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:bobbyholley@gmail.com Bobby Holley]
|group=dev-tech-js-engine
|source_dirs=js/src/ctypes/
|url=https://wiki.mozilla.org/JSctypes
|components=Core::js-ctypes
}}

{{Module
|name=js-tests
|description=JavaScript test suite
|owner=[mailto:bclary@bclary.com Bob Clary]
|peers=
|group=dev-tech-js-engine
|source_dirs=js/tests/
|url=http://www.mozilla.org/js/tests/library.html
|components=
}}

{{Module
|name=Layout Engine
|description=rendering tree construction, layout (reflow), etc.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:jfkthame@gmail.com Jonathan Kew], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:matt.woodrow@gmail.com Matt Woodrow], [mailto:xidorn+moz@upsuper.org Xidorn Quan]
|group=dev-tech-layout
|source_dirs=layout/%, layout/base/, layout/build/, layout/doc/, layout/forms/, layout/generic/, layout/html/, layout/printing/, layout/tables/, layout/tools/
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout, Core::Layout: Block and Inline, Core::Layout: Floats, Core::Layout: Form Controls, Core::Layout: HTML Frames, Core::Layout: Images, Core::Layout: Misc Code, Core::Layout: R & A Pos, Core::Layout: Tables, Core::Layout: Text, Core::Print Preview, Core::Printing: Output
}}

{{Module
|name=libjar
|description=The JAR handling code (protocol handler, stream implementation, and zipreader/zipwriter).
|owner=[mailto:mwu@mozilla.com Michael Wu]
|peers=[mailto:aklotz@mozilla.com Aaron Klotz]
|group=dev-platform
|source_dirs=modules/libjar
|url=
|components=
}}

{{Module
|name=MathML
|description=MathML is a low-level specification for describing mathematics which provides a foundation for the inclusion of mathematical expressions in Web pages.
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan]
|group=dev-tech-mathml
|source_dirs=layout/mathml/
|url=http://www.mozilla.org/projects/mathml/
|components=Core::MathML
}}

{{Module
|name=Media Playback
|description=HTML Media APIs, including Media Source Extensions and non-MSE video/audio element playback, and Encrypted Media Extensions. (WebRTC and WebAudio not included).
|owner=[mailto:cpearce@mozilla.com Chris Pearce]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:ajones@mozilla.com Anthony Jones], [mailto:kinetik@flim.org Matthew Gregan], [mailto:eflores@mozilla.com Edwin Flores], [mailto:jyavenard@mozilla.com Jean-Yves Avenard], [mailto:gsquelart@mozilla.com Gerald Squelart], [mailto:rgiles@mozilla.com Ralph Giles], [mailto:jwwang@mozilla.com JW Wang]
|group=dev-media
|source_dirs=dom/media, media/gmp-clearkey/, media/libcubeb/, media/libnestegg/, media/libogg/, media/libopus/, media/libstagefright/, media/libtheora/, media/libtremor/, media/libvorbis/, media/libvpx/, media/omx-plugin/, media/rlz/
|url=
|components=Core::Audio/Video
}}

{{Module
|name=Media Transport
|description=Pluggable transport for real-time media
|owner=[mailto:ekr@rtfm.com Eric Rescorla]
|peers=[mailto:bcampen@mozilla.com Byron Campen], [mailto:abr@mozilla.com Adam Roach], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|group=dev-media
|source_dirs=media/mtransport
|url=
|components=Core::WebRTC::Networking
}}

{{Module
|name=Memory Allocator
|description=Most things related to memory allocation in Gecko, including jemalloc, replace-malloc, DMD (dark matter detector), logalloc, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:n.nethercote@gmail.com Nicholas Nethercote], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-platform
|source_dirs=memory/
|components=Core::DMD, Core::jemalloc
}}

{{Module
|name=mfbt
|description=mfbt is a collection of headers, macros, data structures, methods, and other functionality available for use and reuse throughout all Mozilla code (including SpiderMonkey and Gecko more broadly).
|owner=[mailto:jwalden@mit.edu Jeff Walden]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd], [mailto:Ms2ger@gmail.com Ms2ger], [mailto:mh+mozilla@glandium.org Mike Hommey]
|group=dev-platform
|source_dirs=mfbt/
|url=
|components=Core::MFBT
}}

{{Module
|name=mozApps API & UI
|description=Implementation of the navigator.mozApps API
|owner=[mailto:fabrice@mozilla.com Fabrice Desré], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:myk@mozilla.org Myk Melez], [mailto:mar.castelluccio@studenti.unina.it Marco Castelluccio], [mailto:ferjmoreno@gmail.com Fernando Jiménez]
|group=dev-webapi
|source_dirs=dom/apps/, dom/interfaces/apps, product specific files implementing UI hooks.
|url=
|components=Core::DOM: Apps
}}

{{Module
|name=Mozglue
|description=Glue library containing various low-level functionality, including a dynamic linker for Android, a DLL block list for Windows, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd] (mozglue/linker), [mailto:kgupta@mozilla.com Kartikaya Gupta] (mozglue/android), [mailto:nchen@mozilla.com Jim Chen] (mozglue/android)
|group=dev-platform
|source_dirs=mozglue/
|components=Core::mozglue
}}

{{Module
|name=mozilla-toplevel
|description=The top level directory for the mozilla tree.
|owner=[mailto:brendan@mozilla.org Brendan Eich]
|peers=
|group=
|source_dirs=tools/README
|url=
|components=
}}

{{Module
|name=MSCOM
|description=Integration with Microsoft Distributed COM
|owner=[mailto:aklotz@mozilla.com Aaron Klotz]
|peers=[mailto:jmathies@mozilla.com Jim Mathies]
|group=dev-platform
|source_dirs=ipc/mscom/%
|url=
|components=Core::IPC: MSCOM}}

{{Module
|name=Necko
|description=The Mozilla Networking Library
|owner=[mailto:mcmanus@ducksong.com Patrick McManus]
|peers= [mailto:jduell.mcbugs@gmail.com Jason Duell], [mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:mnovotny@mozilla.com Michal Novotny], [mailto:hurley@mozilla.com Nick Hurley], [mailto:dd.mozilla@gmail.com Dragana Damjanovic ],[mailto:valentin.gosu@gmail.com Valentin Gosu],[mailto:daniel@haxx.se Daniel Stenberg ], [mailto:schien@mozilla.com ShihChiang Chien]
|peersemeritus= [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sworkman@mozilla.com Steve Workman], [mailto:bzbarsky@mit.edu Boris Zbarsky]
|group=dev-tech-network
|source_dirs=netwerk/%, netwerk/base/, netwerk/build/, netwerk/cache/, netwerk/dns/, netwerk/locales/, netwerk/mime/, netwerk/protocol/, netwerk/resources/, netwerk/socket/, netwerk/streamconv/, netwerk/system/, netwerk/test/, netwerk/testserver/
|url=http://www.mozilla.org/projects/netlib/, https://developer.mozilla.org/en/Necko
|components=Core::Networking, Core::Networking: Cache, Core::Networking: Cookies, Core::Networking: FTP, Core::Networking: File, Core::Networking: HTTP, Core::Networking: JAR, Core::Networking: Websockets
}}

{{Module
|name=NSPR
|description=Netscape Portable Runtime
|owner=[mailto:kaie@kuix.de Kai Engert]
|peers=[mailto:wtc@google.com Wan-Teh Chang], [mailto:mh@glandium.org Mike Hommey]
|group=dev-tech-nspr
|source_dirs=nsprpub/
|url=http://www.mozilla.org/projects/nspr/
http://www.mozilla.org/projects/nspr/reference/html/
http://www.mozilla.org/projects/nspr/release-notes/
|components=NSPR
}}

{{Module
|name=PDF
|description=Rendering code to display documents encoded in the ISO 32000-1 `PDF' format.
|owner=Chris Jones, Andreas Gal
|peers=[mailto:aadib@mozilla.com Artur Adib], [mailto:bdahl@mozilla.com Brendan Dahl], [mailto:vnicolas@mozilla.com Vivien Nicolas]
|group=dev-platform
|source_dirs=media/pdf/
|url=https://github.com/mozilla/pdf.js
|components=Core::PDF
}}

{{Module
|name=Plugins
|description= NPAPI Plugin support.
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:joshmoz@gmail.com Josh Aas]
|peersemeritus=[mailto:john@pointysoftware.net John Schoenick], [mailto:robert@ocallahan.org Robert O'Callahan], [mailto:jstenback@gmail.com Johnny Stenback], Benjamin Smedberg
|group=
|source_dirs=dom/plugins/, modules/plugin/
|url=https://wiki.mozilla.org/Plugins
|components=Core::Plug-ins
}}

{{Module
|name=Preferences
|description=Preference library
|owner=[mailto:nnethercote@mozilla.com Nicholas Nethercote]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd], [mailto:felipe@mozilla.com Felipe Gomes], [mailto:glandium@mozilla.com Mike Hommey], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-platform
|source_dirs=modules/libpref/
|url=
|components=Core::Preferences: Backend
}}

{{Module
|name=Private Browsing
|description=Implementation of the Private Browsing mode, and the integration of other modules with Private Browsing APIs.
|owner=[mailto:josh@joshmatthews.net Josh Matthews] (while Ehsan is away)
|peers=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=Implementation and consumers of Private Browsing APIs in nsILoadContext, nsIPrivateBrowsingChannel, PrivateBrowsingUtils.jsm and the related glue code.
|url=https://wiki.mozilla.org/Private_Browsing
|components=Firefox::Private Browsing
}}

{{Module
|name=Privilege Manager
|description="caps"
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peersemeritus=[mailto:brendan@mozilla.org Brendan Eich], [mailto:jstenback@gmail.com Johnny Stenback], [mailto:dveditz@mozilla.com Dan Veditz]
|group=dev-tech-dom
|source_dirs=caps/
|url=http://www.mozilla.org/projects/security/components/index.html
|components=Core::Security: CAPS
}}

{{Module
|name=Push Notifications
|description=Push is a way for application developers to send messages to their web applications.
|owners=
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:nsm.nikhil@gmail.com Nikhil Marathe], [mailto:kcambridge@mozilla.com Kit Cambridge], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:ddamjanovic@mozilla.com Dragana Damjanovic]
|group=
|source_dirs=dom/push, dom/simplepush
|url=
|components=
}}

{{Module
|name=PyXPCOM
|description=The Python to XPCOM bridge.
|owner=Todd Whiteman
|peers=[mailto:mhammond@skippinet.com.au Mark Hammond]
|group=
|source_dirs=extension/python
|url=https://developer.mozilla.org/en/PyXPCOM
|components=
}}

{{Module
|name=RDF
|description=
|owner=[mailto:axel@pike.org Axel Hecht]
|peers=
|group=dev-tech-rdf
|source_dirs=rdf/
|url=http://www.mozilla.org/rdf/doc/
|components=Core::RDF
}}

{{Module
|name=security
|description=Crypto/PKI code, including NSS (Network Security Services) and JSS (NSS for Java)
|owner=[mailto:rrelyea@redhat.com Bob Relyea], [mailto:ttaubert@mozilla.com Tim Taubert]
|peers=[mailto:emaldona@redhat.com Elio Maldonado], [mailto:kaie@kuix.de Kai Engert], [mailto:ryan.sleevi@gmail.com Ryan Sleevi], [mailto:ekr@rtfm.com Eric Rescorla], [mailto:franziskuskiefer@gmail.com Franziskus Kiefer], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:wtc@google.com Wan-Teh Chang]
|group=dev-tech-crypto
|source_dirs=dbm/, security/coreconf/, security/dbm/, security/jss/, security/nss/, security/tinderbox/, security/tinderlight/
|url=http://mozilla.org/projects/security/pki/
|components=NSS, JSS, Core::Security, Core::Security: S/MIME
}}

{{Module
|name=Security - Mozilla PSM Glue
|description=Personal Security Manager
|owner=[mailto:dkeeler@mozilla.com David Keeler]
|peers=[mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:cykesiopka.bmo@gmail.com Cykesiopka]
|group=dev-tech-crypto
|source_dirs=security/manager/
|url=
|components=Core::Security: PSM, Core::Security: UI
}}

{{Module
|name=Static analysis & rewriting for C++
|description=Tools for checking C++ code looking for problems at compile time, plus tools for automated rewriting of C++ code.
|owner=[mailto:nika@thelayzells.com Nika Layzell] (while Ehsan is away)
|peers=[mailto:sfink@mozilla.com Steve Fink], [mailto:jrmuizel@mozilla.com Jeff Muizelaar], [mailto:birunthan@mohanathas.com Birunthan Mohanathas], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=build/clang-plugin, tools/rewriting among other out of tree tools
|url=
|components=Core::Rewriting & Analysis
}}
{{Module
|name=storage
|description=Storage APIs with a SQLite backend
|owner=[mailto:mak77@bonardo.net Marco Bonardo]
|peers=[mailto:bugmail@asutherland.org Andrew Sutherland], [mailto:jvarga@mozilla.com Jan Varga]
|group=dev-platform
|source_dirs=db/sqlite3/, storage/
|url=http://developer.mozilla.org/en/docs/Storage
|components=Toolkit::Storage, Core::SQL
}}

{{Module
|name=String
|description=
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[https://mozillians.org/en-US/u/froydnj/ Nathan Froyd], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-tech-xpcom
|source_dirs=string/, xpcom/string/
|url=https://developer.mozilla.org/En/Mozilla_internal_string_guide
|components=Core::String
}}

{{Module
|name=Style System
|description=CSS style sheet handling; style data computation
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:cam@mcc.id.au Cameron McCormack]
|group=dev-tech-layout
|source_dirs=layout/style/
|url=https://wiki.mozilla.org/Gecko:Overview#Style_System
|components=Core::CSS Parsing and Computation
}}

{{Module
|name=SVG
|description=Scalable Vector Graphics
|owner=[mailto:jwatt@jwatt.org Jonathan Watt]
|peers=[mailto:longsonr@gmail.com Robert Longson], [mailto:robert@ocallahan.org Robert O'Callahan], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:birtles@gmail.com Brian Birtles]
|group=dev-tech-svg
|source_dirs=dom/svg/, layout/svg/, dom/smil/
|url=https://developer.mozilla.org/en-US/docs/Web/SVG
|components=Core::SVG
}}

{{Module
|name=Tamarin
|description=VM for ActionScript and JavaScript
|owner=Edwin Smith, [mailto:jodyer@adobe.com Jeff Dyer]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:stejohns@adobe.com Steven Johnson], [mailto:tierney@adobe.com Erik Tierney], [mailto:treilly@adobe.com Tom Reilly]
|group=dev-tech-js-engine
|source_dirs=js/tamarin
|url=http://www.mozilla.org/projects/tamarin/
http://wiki.mozilla.org/tamarin/
http://hg.mozilla.org/tamarin-central/
http://hg.mozilla.org/tamarin-tracing/
|components=Tamarin
}}

{{Module
|name=Test Harness
|description=In-tree test infrastructure and tools. Harnesses include, XPCShell, Mochitest (& Chrome), Reftest, JsREftest, Compiled Code Tests, Robocop, Mozmill, Marionette, Firefox UI Tests. Requests for new harnesses should go to Testing::General.
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:dbaron@dbaron.org David Baron] (reftest), [mailto:jwalden@mit.edu Jeff Walden] (httpd.js, jsreftest), Rob Campbell (mochitest, mochitest chrome, marionette), [mailto:jmaher@mozilla.com Joel Maher] (reftest, mochitest, jsreftest), [mailto:ctalbert@mozilla.com Clint Talbert] (reftest, compiled code, mozmill), [mailto:geoffbrown@mozilla.com Geoff Brown] (robocop), [mailto:hskupin@mozilla.com Henrik Skupin] (Marionette, Firefox UI tests), [mailto:ato@mozilla.com Andreas Tolfsen] (marionette), [mailto:jgriffin Jonathan Griffin] (marionette), [mailto:dburns@mozilla.com David Burns] (marionette), [mailto:dminor@mozilla.com Dan Minor], [mailto:mjzffr@gmail.com Maja Frydrychowicz] (Marionette, Firefox UI tests),

|group=dev-quality
|source_dirs=/testing
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::General, Testing::Mochitest, Testing::Mochitest Chrome, Testing::Marionette, Testing::Mozmill, Testing::Reftest, Testing::XPCShell Harness, Testing::httpd.js
}}

{{Module
|name=Testing Infrastructure
|description=Testing tools and infrastructure for Mozilla projects, harnesses for automated tests, stand-alone test tools. Talos, Graph Server, Mozbase, Pulse, WOO, Bughunter, SUTAgent, Eideticker
|owner=[mailto:jmaher@mozilla.com Joel Maher]
|peers=[mailto:bclary@bclary.com Bob Clary], [mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:ccooper@deadsquid.com Chris Cooper], [mailto:ctalbert@mozilla.com Clint Talbert], [mailto:robert@roberthelmer.com Robert Helmer], [mailto:jmaher@mozilla.com Joel Maher], Rob Campbell, [mailto:wlach@mozilla.com William Lachance], [mailto:jeads@mozilla.com Jonathan Eads], [mailto:jgriffin Jonathan Griffin], [mailto:bmoss@mozilla.com Bob Moss], [mailto:mcote@mozilla.com Mark Côté]
|group=dev-quality
|source_dirs=testing/, tools/httptester/, tools/page-loader/, tools/test-harness/, tools/tests/, tools/testserver/, tools/testy/
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::Infrastructure
}}

{{Module
|name=JS Marionette
|description=NodeJS test harness, marionette client, and other utilities for running marionette tests (submodule of Test Infrastructure)
|owner=[mailto:jlal@mozilla.com James Lal] <lightsofapollo>, [mailto:gaye@mozilla.com Gareth Aye] <gaye>
|peers=[mailto:aus@mozilla.com Ghislain "Aus" Lacroix] <auswerk>
|source_dirs=gaia/tests/jsmarionette
|components=Testing::JSMarionette
|group=dev-gaia
}}

{{Module
|name=XPCShell Test Harness
|description=The XPCShell Harness
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:jmaher@mozilla.com Joel Maher]
|source_dirs=testing/xpcshell
|components=Testing::XPCShell Harness
}}

{{Module
|name=Update Service
|description=server code for Mozilla Update services (aus, addons, pfs)
|owner=Mike Morgan
|peers=[mailto:jscott@mozilla.com Justin Scott], [mailto:shaver@mozilla.org Mike Shaver], [mailto:wclouser@mozilla.com Will Clouser]
|group=dev-amo
|source_dirs=webtools/addons/, webtools/aus/, webtools/update/
|url=http://wiki.mozilla.org/wiki/AMO
|components=AUS::Administration, AUS::Systems
}}

{{Module
|name=View System
|description=The View Manager is responsible for handling "heavyweight" rendering (some clipping, compositing) and event handling tasks.
|owner=[mailto:mstange@themasta.com Markus Stange]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dbaron@dbaron.org David Baron]
|group=dev-tech-layout
|source_dirs=view/
|url=
|components=Core::Layout: View Rendering
}}

{{Module
|name=Web Audio
|description=Support for the W3C Web Audio API specification.
|owner=[mailto:padenot@mozilla.com Paul Adenot]
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:karlt+@karlt.net Karl Tomlinson]
|group=dev-platform
|source_dirs=dom/media/webaudio
|url=https://wiki.mozilla.org/Web_Audio_API
|components=Core::Web Audio
}}

{{Module
|name=Web Painting
|description=painting, display lists, and layer construction
|owner=[mailto:matt.woodrow@gmail.com Matt Woodrow]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:dbaron@dbaron.org David Baron], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:mstange@themasta.com Markus Stange]
|group=dev-tech-layout
|source_dirs= layout/painting, the display list and layer related methods on nsIFrame and its subclasses
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout: Web Painting
}}

{{Module
|name=WebRTC
|description=WebRTC is responsible for realtime audio and video communication, as well as related issues like low-level camera and microphone access
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:bcampen@mozilla.com Byron Campen] [mailto:abr@mozilla.com Adam Roach]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=netwerk/sctp (also see submodules "WebRTC Media" and "WebRTC Signaling")
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC, Core::WebRTC Networking
}}

{{Module
|name=WebVR
|description=Gecko's implementation of WebVR (Virtual Reality) functionality, including API, devices, graphics and integration
|owner=[mailto:kgilbert@mozilla.com Kip Gilbert]
|peers=[mailto:dmu@mozilla.com Daosheng Mu]
|peersemeritus=[mailto:vladimir@pobox.com Vladimir Vukicevic]
|group=dev-platform
|source_dirs=dom/vr, gfx/vr
|url=https://mozvr.com/
|components=Core::WebVR
}}

{{Module
|name=Widget
|description=
|owner=[mailto:vladimir@pobox.com Vladimir Vukicevic]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peersemeritus=[mailto:pavlov@pavlov.net Stuart Parmenter],
|group=dev-platform
|source_dirs=widget/, widget/xpwidgets/
|url=
|components=Core::Drag and Drop, Core::Widget, Core::Printing: Setup
}}

{{Module
|name=Widget - Android
|description=The Android Port
|owner=[mailto:blassey.bugs@lassey.us Brad Lassey]
|peers=[mailto:jwillcox@mozilla.com James Willcox]
|group=dev-platforms-mobile
|source_dirs=widget/android/, embedding/android
|url=
|components=Core::Widget: Android
}}

{{Module
|name=Widget - GTK
|description=supported X widgetry and gfx
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|group=dev-platform
|source_dirs=widget/gtk/, widget/gtk2/, widget/gtksuperwin/, widget/gtkxtbin/
|url=http://www.mozilla.org/unix/, http://www.gtk.org, http://www.mozilla.org/ports/gtk/
|components=Core::Widget: Gtk
}}

{{Module
|name=Widget - OS X
|description= Gecko's OS X compatibility layer.
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:joshmoz@gmail.com Josh Aas], [mailto:bgirard@mozilla.com Benoit Girard], [mailto:spohl@mozilla.com Stephen Pohl], [mailto:smichaud@pobox.com Steven Michaud]
|group=dev-platform
|source_dirs=widget/cocoa/
|url=
|components=Core::Widget: Cocoa
}}

{{Module
|name=Widget - Windows
|description=Windows widgets and desktop integration
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook], [mailto:vladimir@pobox.com Vladimir Vukicevic], [mailto:jmathies@mozilla.com Jim Mathies]
|peersemeritus=[mailto:blassey@mozilla.com Brad Lassey], [mailto:netzen@gmail.com Brian Bondy], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:doug.turner@gmail.com Doug Turner], [mailto:timeless@mozdev.org Josh 'timeless' Soref], [mailto:robarnold@cmu.edu Rob Arnold]
|group=dev-platform
|source_dirs=widget/windows/
|url=
|components=Core::Widget: Win32
}}

{{Module
|name=XBL
|description=eXtensible Binding Language
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:jonas@sicking.cc Jonas Sicking]
|ownersemeritus=[mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xbl
|source_dirs=dom/xbl/
|url=http://www.mozilla.org/projects/xbl/
|components=Core::XBL
}}

{{Module
|name=XML
|description=XML in Mozilla, including XML, XHTML, Namespaces in XML, Associating Style Sheets with XML Documents, XML Linking and XML Extras. XML-related things that are not covered by more specific projects.
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-tech-xml
|source_dirs=dom/xml/, extensions/xmlextras/, parser/expat/
|url=http://www.mozilla.org/newlayout/xml/
|components=Core::XML
}}

{{Module
|name=XPApps
|description=Cross-Platform Applications, mostly Navigator front end and application shell.
|owner=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|peers=[mailto:dean_tessman@hotmail.com Dean Tessman], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-apps-seamonkey
|source_dirs=xpfe/
|url=http://www.mozilla.org/xpapps/
|components=
}}

{{Module
|name=XPCOM
|description=The cross-platform object model and core data structures.
|owner=[https://mozillians.org/en-US/u/froydnj/ Nathan Froyd]
|peers=[mailto:erahm@mozilla.com Eric Rahm]
|ownersemeritus=Benjamin Smedberg
|peersemeritus=[https://mozillians.org/en-US/u/dougt/ Doug Turner]
|group=dev-platform
|source_dirs=startupcache/, xpcom/%, xpcom/base/, xpcom/build/, xpcom/components/, xpcom/ds/, xpcom/glue/, xpcom/proxy/, xpcom/sample/, xpcom/stub/, xpcom/tests/, xpcom/threads/, xpcom/tools/, xpcom/windbgdlg/
|url=http://developer.mozilla.org/en/XPCOM
|components=Core::XPCOM
}}

{{Module
|name=XPConnect
|description=Deep Magic
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:gkrizsanits@mozilla.com Gabor Krizsanits], [mailto:amccreight@mozilla.com Andrew McCreight], [mailto:kmaglione@mozilla.com Kris Maglione]
|peersemeritus=[mailto:gal@uci.edu Andreas Gal], [mailto:jstenback@gmail.com Johnny Stenback]
|group=
|source_dirs=js/xpconnect/
|url=
|components=Core::XPConnect
}}

{{Module
|name=XPIDL
|description=Cross-platform IDL compiler; produces .h C++ header files and .xpt runtime type description files from .idl interface description files.
|owner=[mailto:me@kylehuey.com Kyle Huey]
|peersemeritus=[mailto:shaver@mozilla.org Mike Shaver], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-tech-xpcom
|source_dirs=xpcom/typelib/
|url=http://www.mozilla.org/scriptable/xpidl
http://www.mozilla.org/scriptable
|components=
}}

{{Module
|name=XPInstall
|description=
|owner=[mailto:dveditz@mozilla.com Dan Veditz]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|group=dev-tech-xpinstall
|source_dirs=xpinstall/
|url=
|components=Core::Installer: XPInstall Engine
}}

{{Module
|name=XPToolkit
|description=Cross-platform user interface toolkit
|owner=
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:Jan.Varga@gmail.com Jan Varga]
|group=dev-tech-xul
|source_dirs=dom/xul/, layout/xul/
|url=http://www.mozilla.org/xpfe/
|components=Core::XP Toolkit/Widgets: Menus, Core::XP Toolkit/Widgets: XUL
}}

{{Module
|name=XSLT Processor
|description=XSLT transformations processor
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:axel@pike.org Axel Hecht], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xslt
|source_dirs=dom/xslt/
|url=http://www.mozilla.org/projects/xslt/, http://www.w3.org/TR/xslt.html
|components=Core::XSLT
}}

{{Module
|name=Sandboxing
|description=Cross platform sandboxing
|owner=[mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|peers=[mailto:bowen@mozilla.com Bob Owen], [mailto:aklotz@mozilla.com Aaron Klotz], [https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes], [mailto:gDestuynder@mozilla.com Guillaume Destuynder], [mailto:jld@mozilla.com Jed Davis]
|group=dev-platform
|source_dirs=security/sandbox
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Windows
|description=Sandboxing for the Windows platform
|owner=[mailto:bowen@mozilla.com Bob Owen]
|peers=[mailto:netzen@gmail.com Brian Bondy], [mailto:aklotz@mozilla.com Aaron Klotz], [https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes], [mailto:jimm@mozilla.com Jim Mathies]
|group=dev-platform
|source_dirs=security/sandbox/win
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - OSX
|description=Sandboxing for the OSX platform
|owner=[mailto:haftandilian@mozilla.com Haik Aftandilian]
|peers=
|group=dev-platform
|source_dirs=security/sandbox/mac
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Linux & B2G
|description=Sandboxing for the Linux & B2G platforms
|owner=[mailto:jhector@mozilla.com Julian Hector]
|peers=[mailto:jld@mozilla.com Jed Davis] [mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|group=dev-platform
|source_dirs=security/sandbox/linux
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

===Submodules===
{{Module
|name=Build Config - Fennec
|description=Submodule of the build config covering Fennec's build system in mobile/android.
|owner=[mailto:nalexander@mozilla.com Nicholas Alexander]
|peers=Same as Build Config
|group=dev-builds
|components=Core::Build Config
}}

{{Module
|name=WebRTC Media
|description=Submodule of WebRTC responsible for access to media input devices (microphones, cameras, screen capture), as well as realtime audiovisual codecs and packetization.
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:jib@mozilla.com Jan-Ivar Bruaroey], [mailto:dminor@mozilla.com Dan Minor], [mailto:apehrson@mozilla.com Andreas Pehrson],
|peersemeritus=[mailto:pkerr@mozilla.com Paul Kerr], [mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=/media/webrtc, /dom/media/webrtc, /dom/media/systemservices
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Audio/Video)
}}

{{Module
|name=WebRTC Signaling
|description=Submodule of WebRTC responsible for implementation of PeerConnection API, WebRTC identity, and SDP/JSEP handling
|owner=[mailto:bcampen@mozilla.com Byron Campen]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:abr@mozilla.com Adam Roach], [mailto:rjesup@mozilla.com Randell Jesup], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=/media/webrtc/signaling/
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Signaling)
}}

<noinclude>

===Unassigned Bugzilla Components===

The following Bugzilla components in the Core project have not been assigned to a module (this list is not exhaustive):

<pre>
Core::File Handling
Core::Find Backend
Core::Gecko Profiler
Core::General
Core::HTML: Form Submission
Core::History: Global
Core::Image Blocking
Core::JavaScript Debugging APIs
Core::Localization
Core::Nanojit
Core::Networking: Domain Lists
Core::Print Preview
Core::Printing: Output
Core::Printing: Setup
Core::Profile: BackEnd
Core::Profile: Migration
Core::Profile: Roaming
Core::QuickLaunch (AKA turbo mode)
Core::Rewriting and Analysis
Core::Selection
Core::Serializers
Core::Spelling checker
Core::Tracking
Core::Web Services
Core::WebDAV
Core::Widget: OS/2
Core::Widget: Photon
Core::X-remote
Core::XForms
Core::XUL
</pre>
</noinclude>

Modules/Core

2017-05-30T23:58:16Z

Surkov.alexander:

<noinclude>
'''Only module owners may edit this page.'''

They may:

* update any information about their module except the name of the owner
* add or remove sub-modules
* change the owner of a sub-module
* add emeritus owners or peers

Other changes, including changes of module owner or addition/removal of modules, must be agreed with the Module Ownership Module group, probably via a discussion in [https://www.mozilla.org/about/forums/#governance mozilla.governance].
</noinclude>
{{Module
|name=Accessibility
|description=Support for platform accessibility APIs. Accessibility APIs are used by 3rd party software like screen readers, screen magnifiers, and voice dictation software, which need information about document content and UI controls, as well as important events like changes of focus.
|owner=[mailto:surkov.alexander@gmail.com Alexander Surkov]
|peers=[mailto:dbolter@mozilla.com David Bolter], [mailto:eitan@monotonous.org Eitan Isaacson],[mailto:tbsaunde+mozbugs@tbsaunde.org Trevor Saunders], [mailto:mzehe@mozilla.com Marco Zehe], [mailto:yzenevich@mozilla.com Yura Zenevich]
|ownersemeritus=[mailto:aaron@moonset.net. Aaron Leventhal]
|peersemeritus=[mailto:ginn.chen@oracle.com Ginn Chen], Evan Yan
|group=dev-accessibility
|source_dirs=accessible/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=Browser WebAPI
|description=Web API for rendering apps, browser windows and widgets.
|owner=[mailto:kchen@mozilla.com Kan-Ru Chen]
|peers=[mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:fabrice@mozilla.com Fabrice Desré]
|group=dev-webapi
|source_dirs=dom/browser-element/
|url=
|components=Core::DOM
}}

{{Module
|name=Build and Release Tools
|description=Tools related to build and release automation and configuration of release builds.
|owner=[mailto:nthomas@mozilla.com Nick Thomas]
|peers=[mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:coop@mozilla.com Chris Cooper]
|group=release-engineering
|source_dirs=browser/config/mozconfigs/, mobile/android/config/mozconfigs/, xulrunner/config/mozconfigs/, b2g/config/, tools/update-packaging/
|url=https://wiki.mozilla.org/ReleaseEngineering
|components=Release Engineering::*
}}

{{Module
|name=Build Config
|description=The build system for Gecko and several mozilla.org hosted Gecko-based applications.
|owner=[mailto:gps@mozilla.com Gregory Szorc] (:gps)
|peers=[mailto:mh@glandium.org Mike Hommey] (:glandium), [mailto:mshal@mozilla.com Mike Shal] (:mshal), [mailto:ted@mielczarek.org Ted Mielczarek] (:ted), [mailto:cmanchester@mozilla.com Chris Manchester](:chmanchester), [mailto:nfroyd@mozilla.com Nathan Froyd] (:froydnj), [mailto:rgiles@mozilla.com Ralph Giles] (:rillian)
|ownersemeritus=Ted Mielczarek (2008-[https://blog.mozilla.org/ted/2013/03/07/gregory-szorc-is-now-the-build-config-module-owner/ 2013]), Benjamin Smedberg (???-[http://benjamin.smedbergs.us/blog/2008-04-30/more-changing-of-the-guard-ted-mielczarek/ 2008]),
|group=dev-builds
|source_dirs=build/, config/, python/mozbuild, tools/cross-commit, tools/cvs2hg-import.py, tools/cvsmgmt/, tools/elf-dynstr-gc/, tools/trees.pl, browser/config/mozconfigs/, mobile/config/mozconfigs/, xulrunner/config/mozconfigs/
|url=http://www.mozilla.org/build/
|components=Core::Build Config
}}

{{Module
|name=Code Analysis and Debugging Tools
|description=Tools for debugging Mozilla code or for analyzing speed, memory use, and other characteristics of it.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=
|group=dev-performance
|source_dirs=tools/codesighs/, tools/debug/, tools/dreftool/, tools/dumpdeps/, tools/footprint/, tools/jprof/, tools/leaky/, tools/memory/, tools/module-deps/, tools/performance/, tools/post_compile/, tools/preloader/, tools/rb/, tools/reorder/, tools/trace-malloc/, tools/uuiddeps/,
|url=
|components=
}}

{{Module
|name=Content HTTP Headers
|description=HTTP headers related to content, e.g. User-Agent, Content-Type, Accept. (Transport-related headers are the responsibility of the Necko module owner.)
|owner=[mailto:gerv@mozilla.org Gervase Markham]
|peers=[mailto:lmandel@mozilla.com Lawrence Mandel]
|group=dev-platform
|source_dirs=
|url=https://developer.mozilla.org/en/Gecko_user_agent_string_reference
|components=Core::Networking: HTTP
}}

{{Module
|name=Content Security
|description=Native content-based security features, including: Content Security Policy (CSP), Mixed Content Blocker (MCB), Subresource Integrity (SRI) and CORS.
|owner=[mailto:ckerschbaumer@mozilla.com Christoph Kerschbaumer]
|peers=[mailto:francois@mozilla.com François Marier], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:tvyas@mozilla.com Tanvi Vyas], [mailto:dveditz@mozilla.com Dan Veditz], [mailto:mozilla@sidstamm.com Sid Stamm]
|group=dev-security
|source_dirs=dom/security
|components=Core::DOM: Security
}}

{{Module
|name=Cookies and Permissions
|description=
|owner=Monica Chew
|peers=[mailto:josh@joshmatthews.com Josh Matthews], [mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:mconnor@steelgryphon.com Mike Connor], [mailto:dwitte@gmail.com Dan Witte], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sdwilsh@shawnwilsher.com Shawn Wilsher (ping on irc)]
|group=dev-tech-network
|source_dirs=extensions/cookie/, netwerk/cookie/
|url=
|components=Core::Networking: Cookies
}}
{{Module
|name=Cycle Collector
|description=Code to break and collect objects within reference cycles
|owner=[https://mozillians.org/en-US/u/mccr8/ Andrew McCreight]
|peers=Peter Van der Beken, Olli Pettay, David Baron
|source_dirs=xpcom/base/nsCycleCollector.* and some support headers
|components=Core::XPCOM
|group=dev-platform
}}
{{Module
|name=C++/Rust usage, tools, and style
|description=Aspects of C++ use such as language feature usage, standard library versions/usage, compiler/toolchain versions, formatting and naming style, and aspects of Rust use as needs arise
|owner=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:nfroyd@mozilla.com Nathan Froyd], [mailto:glandium@mozilla.com Mike Hommey], [mailto:jwalden@mozilla.com Jeff Walden]
|source_dirs=non-third-party C++ and Rust code in the tree
|components=Various components
|group=dev-platform
}}
{{Module
|name=docshell
|description=
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:justin.lebar@gmail.com Justin Lebar]
|peersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-tech-layout
|source_dirs=docshell/, uriloader/
|url=
|components=Core::Document Navigation
}}

{{Module
|name=Device Storage
|description=Support for the device storage API
|owner=[https://mozillians.org/u/dhylands/ Dave Hylands] (:dhylands), [mailto:jvarga@mozilla.com Jan Varga] (:janv)
|peers=
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner] (:dougt)
|group=dev-tech-dom
|source_dirs=dom/devicestorage/, dom/interfaces/devicestorage/
|url=https://developer.mozilla.org/en-US/docs/WebAPI/Device_Storage
|components=Core::DOM: Device Interfaces
}}

{{Module
|name=Document Object Model
|description=
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:bent.mozilla@gmail.com Ben Turner], [mailto:mounir@lamouri.fr Mounir Lamouri (still active, but slower to respond than previously)], [mailto:me@kylehuey.com Kyle Huey], [mailto:hsivonen@iki.fi Henri Sivonen], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:baku@mozilla.com Andrea Marchesini],
[mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:bkelly@mozilla.com Ben Kelly], [mailto:billm@mozilla.com Bill McCloskey], [mailto:kyle@nonpolynomial.com Kyle Machulis]
|ownersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|peersemeritus=[mailto:justin.lebar@gmail.com Justin Lebar]
|group=dev-tech-dom
|source_dirs=dom/*, except directories covered by other modules
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM, Core::DOM: CSS Object Model, Core::DOM: Core & HTML
}}

{{Module
|name=DOM File
|description=DOM Blob, File and FileSystem APIs
|owner=[mailto:amarchesini@Mozilla.com Andrea Marchesini]
|peers=[mailto:olli@pettay.fi Olli Pettay]
|group=dev-platform
|source_dirs=dom/file, dom/filesystem
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: File
}}

{{Module
|name=Event Handling
|description=DOM Events and Event Handling
|owner=[mailto:olli@pettay.fi Olli Pettay], [mailto:masayuki@d-toybox.com Masayuki Nakano]
|group=dev-platform
|source_dirs=dom/events and event handling related code elsewhere
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: Events, Core::Event Handling
}}

{{Module
|name=Web Workers
|description=
|owner=[mailto:baku@mozilla.com Andrea Marchesini]
|peers=[mailto:mrbkap@mozilla.com Blake Kaplan], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey], [mailto:bkelly@mozilla.com Ben Kelly]
|ownersemeritus=[mailto:bent.mozilla@gmail.com Ben Turner]
|group=dev-platform
|source_dirs=dom/workers/
|url=https://developer.mozilla.org/En/Using_web_workers
|components=Core::DOM: Workers
}}

{{Module
|name=IndexedDB
|description=
|owner=[mailto:jvarga@mozilla.com Jan Varga]
|peers=[mailto:btseng@mozilla.com Bevis Tseng]
|ownersemeritus=[mailto:bent.mozilla@gmail.com Ben Turner]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey]
|group=dev-platform
|source_dirs=dom/indexedDB/
|url=https://developer.mozilla.org/en/IndexedDB
|components=Core::DOM: IndexedDB
}}

{{Module
|name=Editor
|description=
|owner=[mailto:masayuki@d-toybox.com Masayuki Nakano]
|peers=[mailto:ayg@aryeh.name Aryeh Gregor]
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=editor/
|url=http://www.mozilla.org/editor/
|components=Core::Editor
}}

{{Module
|name=Embedding
|description=Gecko embedding APIs and frameworks
|owner=[mailto:myk@mykzilla.org Myk Melez]
|ownersemeritus=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:bdahl@mozilla.com Brendan Dahl], [mailto:tbsaunde@tbsaunde.org Trevor Saunders]
|peersemeritus=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-platform
|source_dirs=embedding/
|url=
|components=Core::Embedding: APIs
}}

{{Module
|name=Find As You Type
|description=Find As You Type (formerly called Type Ahead Find) is a feature that allows quick web page navigation when you type a succession of characters in the body of the displayed page (not in an edit box of or drop down list). Currently seeks new owner.
|owner=
|peers=
|group=dev-accessibility
|source_dirs=extensions/typeaheadfind/
|url=http://www.mozilla.org/access/type-ahead/
|components=
}}

{{Module
|name=Gecko Profiler
|description=Gecko's built-in profiler
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:nnethercote@mozilla.com Nicholas Nethercote], [mailto:jseward@mozilla.com Julian Seward] (LUL), [mailto:kvijayan@mozilla.com Kannan Vijayan] (JS integration), [mailto:shu@mozilla.com Shu-yu Guo] (JS integration), [mailto:tlee@mozilla.com Thinker Lee] (TaskTracer), [mailto:cyu@mozilla.com Cervantes Yu] (TaskTracer), [mailto:b56girard@gmail.com Benoit Girard].
|group=dev-platform
|source_dirs=tools/profiler/
|url=https://developer.mozilla.org/en-US/docs/Mozilla/Performance/Profiling_with_the_Built-in_Profiler
|components=Core::Gecko Profiler
}}

{{Module
|name=Geolocation
|description=Implementation of the Geolocation W3C Spec, location provider apis, and wifi scanning code.
|owner=[mailto:josh@joshmatthews.net Josh Matthews], [mailto:kchen@mozilla.com Kan-Ru Chen]
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner], Garvan Keeley
|peers=
|group=dev-tech-dom
|source_dirs=dom/geolocation, dom/system/, netwerk/wifi
|url=https://developer.mozilla.org/En/Using_geolocation
|components=Core::Geolocation
}}

{{Module
|name=Global Key Bindings
|description=Global hot keys in Mozilla for the browser, editor, mail-news and widgets. Does not include underlined menu accelerators and the like, as those are part of i18n.
|owner=Aaron Leventhal
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|group=dev-accessibility
|source_dirs=dom/xbl/builtin/
|url=http://www.mozilla.org/projects/ui/accessibility/mozkeyintro.html
|components=Core::Keyboard: Navigation
}}

{{Module
|name=Graphics
|description=Mozilla graphics API
|owner=[mailto:jrmuizel@mozilla.com Jeff Muizelaar](Thebes, QCMS, YCbCr, Cairo/Pixman, Regions, OS X, Other)
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:jdrew@mozilla.com Joe Drew], [mailto:vladimir@pobox.com Vladimir Vukicevic], [mailto:bas.schouten@live.nl Bas Schouten](Layers, Windows), [mailto:bjacob@mozilla.com Benoit Jacob](gfx/gl), [mailto:bgirard@mozilla.com Benoit Girard](Compositor, Performance), [mailto:ajuma.bugzilla@alijuma.com Ali Juma], [mailto:jgilbert@mozilla.com Jeff Gilbert](WebGL, ANGLE), [mailto:george@mozilla.com George Wright](Canvas2D, Skia), [mailto:mwoodrow@mozilla.com Matt Woodrow](Layers API), [mailto:jdaggett@mozilla.com John Daggett](text/fonts), [mailto:jfkthame@googlemail.com Jonathan Kew](text/fonts), [mailto:nsilva@mozilla.com Nicolas Silva](MozSurface), [mailto:ncameron@mozilla.com Nick Cameron], [mailto:sikeda@mozilla.com Sotaro Ikeda](B2G), [mailto:snorp@mozilla.com James Willcox](Android), [mailto:clord@mozilla.com Christopher Lord], [mailto:mstange@themasta.com Markus Stange](OS X), [mailto:lsalzman@mozilla.com Lee Salzman], [mailto:mchang@mozilla.com Mason Chang], [mailto:dvander@mozilla.com David Anderson]
|group=dev-platform
|source_dirs=gfx/, dom/canvas/
|url=https://wiki.mozilla.org/Platform/GFX https://wiki.mozilla.org/Gecko:Layers https://wiki.mozilla.org/Gecko:2DGraphicsSketch
|components=Core::Graphics, Core::Graphics: Layers, Core::Graphics: Text, Core::GFX: Color Management, Core::Canvas: 2D, Core::Canvas: WebGL
}}

{{Module
|name=APZ (Graphics submodule)
|description=Asynchronous panning and zooming
|owner=[mailto:kgupta@mozilla.com Kartikaya Gupta]
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:tnikkel@mozilla.com Timothy Nikkel], [mailto:dvander@mozilla.com David Anderson], [mailto:mstange@mozilla.com Markus Stange]
|group=dev-platform
|source=gfx/layers/apz
|url=https://wiki.mozilla.org/Platform/GFX/APZ
|components=Core::Panning and Zooming
}}

{{Module
|name=Moz2D (Graphics submodule)
|description=Platform independent 2D graphics API
|owner=[mailto:bschouten@mozilla.com Bas Schouten]
|peers=[mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:gwright@mozilla.com George Wright], [mailto:jwatt@mozilla.com Jonathan Watt]
|group=dev-platform
|source=gfx/2d
|url=https://wiki.mozilla.org/Platform/GFX/Moz2D
|components=Core::Graphics
}}

{{Module
|name=Legacy HTML Parser
|description=
|owner=[mailto:mrbkap@gmail.com Blake Kaplan]
|peers=[mailto:dbaron@dbaron.org David Baron], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:rbs@maths.uq.edu.au rbs@maths.uq.edu.au]
|peersemeritus=[mailto:jstenback@gmail.com Johnny Stenback]
|source_dirs=parser/htmlparser
|url=http://www.mozilla.org/newlayout/doc/parser.html
|components=Core::HTML: Parser
}}

{{Module
|name=HAL
|description=Hardware Abstraction Layer
|owner=[https://mozillians.org/u/dhylands/ Dave Hylands]
|peers=[mailto:gsvelto@mozilla.com Gabriele Svelto]
|group=dev-platform
|source_dirs=hal/
|components=Core::Hardware Abstraction Layer (HAL)
}}

{{Module
|name=HTML Parser
|description=The HTML Parser transforms HTML source code into a DOM. It conforms to the HTML specification, and is mostly translated automatically from Java to C++.
|owner=[mailto:hsivonen@iki.fi Henri Sivonen]
|peers=[mailto:wchen@mozilla.com William Chen]
|group=dev-platform
|source_dirs=parser/html
|url=http://about.validator.nu/
|components=Core::HTML: Parser
}}

{{Module
|name=I18N Library
|description=
|owner=[mailto:jshin1987@gmail.com Jungshik Shin], [mailto:smontagu@smontagu.org Simon Montagu]
|peers=[mailto:VYV03354@nifty.ne.jp Masatoshi Kimura]
|group=dev-i18n
|source_dirs=intl/
|url=http://mozilla.org/projects/intl/index.html
|components=Core::Internationalization
}}

{{Module
|name=ImageLib
|description=
|owner=[mailto:tnikkel@gmail.com Timothy Nikkel]
|peers=[mailto:aosmond@mozilla.com Andrew Osmond], [mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:seth.bugzilla@blackhail.net Seth Fowler]
|peersemeritus=[mailto:netzen@gmail.com Brian Bondy], [mailto:justin.lebar@gmail.com Justin Lebar]
|group=dev-platform
|source_dirs=media/libjpeg/, media/libpng/, image/, modules/zlib/
|url=
|components=Core::ImageLib
}}

{{Module
|name=IPC
|description=Message-passing between threads and processes
|owner=[mailto:wmccloskey@mozilla.com Bill McCloskey]
|peers=[mailto:danderson@mozilla.com David Anderson], [mailto:jld@mozilla.com Jed Davis], [mailto:kchen@mozilla.com Kan-Ru Chen]
|group=dev-platform
|source_dirs=ipc/glue/, ipc/ipdl/, ipc/chromium/
|url=
|components=Core::IPC}}

{{Module
|name=JavaScript
|description=JavaScript engine (SpiderMonkey)
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:jdemooij@mozilla.com Jan de Mooij], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:nnethercote@mozilla.com Nick Nethercote], [mailto:jwalden@mit.edu Jeff Walden], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:evilpies@gmail.com Tom Schuster], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:till@tillschneidereit.net Till Schneidereit], [mailto:efaust@mozilla.com Eric Faust], [mailto:nfitzgerald@mozilla.com Nick Fitzgerald], [mailto:luke@mozilla.com Luke Wagner], [mailto:arai.unmht@gmail.com Tooru Fujisawa], [mailto:sunfish@mozilla.com Dan Gohman], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:nmatsakis@mozilla.com Niko Matsakis], [mailto:ejpbruel@mozilla.com Eddy Bruel], [mailto:danderson@mozilla.com David Anderson], [mailto:igor@mir2.org Igor Bukanov], [mailto:brendan@mozilla.org Brendan Eich], Andreas Gal
|group=dev-tech-js-engine
|source_dirs=js/src
|url=http://www.mozilla.org/js/spidermonkey,
http://developer.mozilla.org/en/docs/About_JavaScript
|components=Core::JavaScript Engine
}}

{{Module
|name=JavaScript JIT
|description=JavaScript engine's JIT compilers (IonMonkey, Baseline)
|owner=[mailto:jdemooij@mozilla.com Jan de Mooij]
|peers=[mailto:danderson@mozilla.com David Anderson], [mailto:bbouvier@mozilla.com Benjamin Bouvier], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:nicolas.b.pierron@mozilla.com Nicolas Pierron], [mailto:evilpies@gmail.com Tom Schuster], [mailto:sstangl@mozilla.com Sean Stangl], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:luke@mozilla.com Luke Wagner]
|group=dev-tech-js-engine-internals
|source_dirs=js/src/jit
|url=http://www.mozilla.org/js/spidermonkey
|components=Core::JavaScript Engine: JIT
}}

{{Module
|name=JavaScript Debugger Backend
|description=JavaScript debugging hooks
|owner=[mailto:timeless@mozdev.org Josh 'timeless' Soref]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:rginda@hacksrus.com Rob Ginda]
|group=dev-apps-js-debugger
|source_dirs=js/jsd/
|url=http://www.mozilla.org/js/jsd
|components=Other Applications::Venkman JS Debugger
}}

{{Module
|name=jsat
|description=Javascript screen reader that is used in Android and B2G
|owner=[mailto:eitan@monotonous.org Eitan Isaacson]
|peers=[mailto:yzenevich@mozilla.com Yura Zenevich]
|group=dev-accessibility
|source_dirs=accessible/jsat/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=js-ctypes
|description=A foreign function interface which allows privileged JS code to interact with binary code without using XPCOM/XPConnect.
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:bobbyholley@gmail.com Bobby Holley]
|group=dev-tech-js-engine
|source_dirs=js/src/ctypes/
|url=https://wiki.mozilla.org/JSctypes
|components=Core::js-ctypes
}}

{{Module
|name=js-tests
|description=JavaScript test suite
|owner=[mailto:bclary@bclary.com Bob Clary]
|peers=
|group=dev-tech-js-engine
|source_dirs=js/tests/
|url=http://www.mozilla.org/js/tests/library.html
|components=
}}

{{Module
|name=Layout Engine
|description=rendering tree construction, layout (reflow), etc.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:jfkthame@gmail.com Jonathan Kew], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:matt.woodrow@gmail.com Matt Woodrow], [mailto:xidorn+moz@upsuper.org Xidorn Quan]
|group=dev-tech-layout
|source_dirs=layout/%, layout/base/, layout/build/, layout/doc/, layout/forms/, layout/generic/, layout/html/, layout/printing/, layout/tables/, layout/tools/
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout, Core::Layout: Block and Inline, Core::Layout: Floats, Core::Layout: Form Controls, Core::Layout: HTML Frames, Core::Layout: Images, Core::Layout: Misc Code, Core::Layout: R & A Pos, Core::Layout: Tables, Core::Layout: Text, Core::Print Preview, Core::Printing: Output
}}

{{Module
|name=libjar
|description=The JAR handling code (protocol handler, stream implementation, and zipreader/zipwriter).
|owner=[mailto:mwu@mozilla.com Michael Wu]
|peers=[mailto:aklotz@mozilla.com Aaron Klotz]
|group=dev-platform
|source_dirs=modules/libjar
|url=
|components=
}}

{{Module
|name=MathML
|description=MathML is a low-level specification for describing mathematics which provides a foundation for the inclusion of mathematical expressions in Web pages.
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan]
|group=dev-tech-mathml
|source_dirs=layout/mathml/
|url=http://www.mozilla.org/projects/mathml/
|components=Core::MathML
}}

{{Module
|name=Media Playback
|description=HTML Media APIs, including Media Source Extensions and non-MSE video/audio element playback, and Encrypted Media Extensions. (WebRTC and WebAudio not included).
|owner=[mailto:cpearce@mozilla.com Chris Pearce]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:ajones@mozilla.com Anthony Jones], [mailto:kinetik@flim.org Matthew Gregan], [mailto:eflores@mozilla.com Edwin Flores], [mailto:jyavenard@mozilla.com Jean-Yves Avenard], [mailto:gsquelart@mozilla.com Gerald Squelart], [mailto:rgiles@mozilla.com Ralph Giles], [mailto:jwwang@mozilla.com JW Wang]
|group=dev-media
|source_dirs=dom/media, media/gmp-clearkey/, media/libcubeb/, media/libnestegg/, media/libogg/, media/libopus/, media/libstagefright/, media/libtheora/, media/libtremor/, media/libvorbis/, media/libvpx/, media/omx-plugin/, media/rlz/
|url=
|components=Core::Audio/Video
}}

{{Module
|name=Media Transport
|description=Pluggable transport for real-time media
|owner=[mailto:ekr@rtfm.com Eric Rescorla]
|peers=[mailto:bcampen@mozilla.com Byron Campen], [mailto:abr@mozilla.com Adam Roach], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|group=dev-media
|source_dirs=media/mtransport
|url=
|components=Core::WebRTC::Networking
}}

{{Module
|name=Memory Allocator
|description=Most things related to memory allocation in Gecko, including jemalloc, replace-malloc, DMD (dark matter detector), logalloc, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:n.nethercote@gmail.com Nicholas Nethercote], [mailto:erahm@mozilla.com Eric Rahm]
|group=dev-platform
|source_dirs=memory/
|components=Core::DMD, Core::jemalloc
}}

{{Module
|name=mfbt
|description=mfbt is a collection of headers, macros, data structures, methods, and other functionality available for use and reuse throughout all Mozilla code (including SpiderMonkey and Gecko more broadly).
|owner=[mailto:jwalden@mit.edu Jeff Walden]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd], [mailto:Ms2ger@gmail.com Ms2ger], [mailto:mh+mozilla@glandium.org Mike Hommey]
|group=dev-platform
|source_dirs=mfbt/
|url=
|components=Core::MFBT
}}

{{Module
|name=mozApps API & UI
|description=Implementation of the navigator.mozApps API
|owner=[mailto:fabrice@mozilla.com Fabrice Desré], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:myk@mozilla.org Myk Melez], [mailto:mar.castelluccio@studenti.unina.it Marco Castelluccio], [mailto:ferjmoreno@gmail.com Fernando Jiménez]
|group=dev-webapi
|source_dirs=dom/apps/, dom/interfaces/apps, product specific files implementing UI hooks.
|url=
|components=Core::DOM: Apps
}}

{{Module
|name=Mozglue
|description=Glue library containing various low-level functionality, including a dynamic linker for Android, a DLL block list for Windows, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd] (mozglue/linker), [mailto:kgupta@mozilla.com Kartikaya Gupta] (mozglue/android), [mailto:nchen@mozilla.com Jim Chen] (mozglue/android)
|group=dev-platform
|source_dirs=mozglue/
|components=Core::mozglue
}}

{{Module
|name=mozilla-toplevel
|description=The top level directory for the mozilla tree.
|owner=[mailto:brendan@mozilla.org Brendan Eich]
|peers=
|group=
|source_dirs=tools/README
|url=
|components=
}}

{{Module
|name=Necko
|description=The Mozilla Networking Library
|owner=[mailto:mcmanus@ducksong.com Patrick McManus]
|peers= [mailto:jduell.mcbugs@gmail.com Jason Duell], [mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:mnovotny@mozilla.com Michal Novotny], [mailto:hurley@mozilla.com Nick Hurley], [mailto:dd.mozilla@gmail.com Dragana Damjanovic ],[mailto:valentin.gosu@gmail.com Valentin Gosu],[mailto:daniel@haxx.se Daniel Stenberg ]
|peersemeritus= [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sworkman@mozilla.com Steve Workman], [mailto:bzbarsky@mit.edu Boris Zbarsky]
|group=dev-tech-network
|source_dirs=netwerk/%, netwerk/base/, netwerk/build/, netwerk/cache/, netwerk/dns/, netwerk/locales/, netwerk/mime/, netwerk/protocol/, netwerk/resources/, netwerk/socket/, netwerk/streamconv/, netwerk/system/, netwerk/test/, netwerk/testserver/
|url=http://www.mozilla.org/projects/netlib/, https://developer.mozilla.org/en/Necko
|components=Core::Networking, Core::Networking: Cache, Core::Networking: Cookies, Core::Networking: FTP, Core::Networking: File, Core::Networking: HTTP, Core::Networking: JAR, Core::Networking: Websockets
}}

{{Module
|name=NSPR
|description=Netscape Portable Runtime
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:wtc@google.com Wan-Teh Chang], [mailto:mh@glandium.org Mike Hommey], [mailto:kaie@kuix.de Kai Engert]
|group=dev-tech-nspr
|source_dirs=nsprpub/
|url=http://www.mozilla.org/projects/nspr/
http://www.mozilla.org/projects/nspr/reference/html/
http://www.mozilla.org/projects/nspr/release-notes/
|components=NSPR
}}

{{Module
|name=PDF
|description=Rendering code to display documents encoded in the ISO 32000-1 `PDF' format.
|owner=Chris Jones, Andreas Gal
|peers=[mailto:aadib@mozilla.com Artur Adib], [mailto:bdahl@mozilla.com Brendan Dahl], [mailto:vnicolas@mozilla.com Vivien Nicolas]
|group=dev-platform
|source_dirs=media/pdf/
|url=https://github.com/mozilla/pdf.js
|components=Core::PDF
}}

{{Module
|name=Plugins
|description= NPAPI Plugin support.
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:joshmoz@gmail.com Josh Aas]
|peersemeritus=[mailto:john@pointysoftware.net John Schoenick], [mailto:robert@ocallahan.org Robert O'Callahan], [mailto:jstenback@gmail.com Johnny Stenback]
|group=
|source_dirs=dom/plugins/, modules/plugin/
|url=https://wiki.mozilla.org/Plugins
|components=Core::Plug-ins
}}

{{Module
|name=Preferences
|description=Preference library
|owner=
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|group=dev-platform
|source_dirs=modules/libpref/
|url=
|components=Core::Preferences: Backend
}}

{{Module
|name=Private Browsing
|description=Implementation of the Private Browsing mode, and the integration of other modules with Private Browsing APIs.
|owner=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:josh@joshmatthews.net Josh Matthews]
|group=dev-platform
|source_dirs=Implementation and consumers of Private Browsing APIs in nsILoadContext, nsIPrivateBrowsingChannel, PrivateBrowsingUtils.jsm and the related glue code.
|url=https://wiki.mozilla.org/Private_Browsing
|components=Firefox::Private Browsing
}}

{{Module
|name=Privilege Manager
|description="caps"
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peersemeritus=[mailto:brendan@mozilla.org Brendan Eich], [mailto:jstenback@gmail.com Johnny Stenback], [mailto:dveditz@mozilla.com Dan Veditz]
|group=dev-tech-dom
|source_dirs=caps/
|url=http://www.mozilla.org/projects/security/components/index.html
|components=Core::Security: CAPS
}}

{{Module
|name=Push Notifications
|description=Push is a way for application developers to send messages to their web applications.
|owners=
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:nsm.nikhil@gmail.com Nikhil Marathe], [mailto:kcambridge@mozilla.com Kit Cambridge], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:ddamjanovic@mozilla.com Dragana Damjanovic]
|group=
|source_dirs=dom/push, dom/simplepush
|url=
|components=
}}

{{Module
|name=PyXPCOM
|description=The Python to XPCOM bridge.
|owner=Todd Whiteman
|peers=[mailto:mhammond@skippinet.com.au Mark Hammond]
|group=
|source_dirs=extension/python
|url=https://developer.mozilla.org/en/PyXPCOM
|components=
}}

{{Module
|name=RDF
|description=
|owner=[mailto:axel@pike.org Axel Hecht]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|group=dev-tech-rdf
|source_dirs=rdf/
|url=http://www.mozilla.org/rdf/doc/
|components=Core::RDF
}}

{{Module
|name=security
|description=Crypto/PKI code, including NSS (Network Security Services) and JSS (NSS for Java)
|owner=[mailto:rrelyea@redhat.com Bob Relyea], [mailto:ttaubert@mozilla.com Tim Taubert]
|peers=[mailto:emaldona@redhat.com Elio Maldonado], [mailto:kaie@kuix.de Kai Engert], [mailto:ryan.sleevi@gmail.com Ryan Sleevi], [mailto:ekr@rtfm.com Eric Rescorla], [mailto:franziskuskiefer@gmail.com Franziskus Kiefer], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:wtc@google.com Wan-Teh Chang]
|group=dev-tech-crypto
|source_dirs=dbm/, security/coreconf/, security/dbm/, security/jss/, security/nss/, security/tinderbox/, security/tinderlight/
|url=http://mozilla.org/projects/security/pki/
|components=NSS, JSS, Core::Security, Core::Security: S/MIME
}}

{{Module
|name=Security - Mozilla PSM Glue
|description=Personal Security Manager
|owner=[mailto:dkeeler@mozilla.com David Keeler]
|peers=[mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:cykesiopka.bmo@gmail.com Cykesiopka]
|group=dev-tech-crypto
|source_dirs=security/manager/
|url=
|components=Core::Security: PSM, Core::Security: UI
}}

{{Module
|name=Static analysis & rewriting for C++
|description=Tools for checking C++ code looking for problems at compile time, plus tools for automated rewriting of C++ code.
|owner=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:sfink@mozilla.com Steve Fink], [mailto:michael@thelayzells.com Michael Layzell], [mailto:jrmuizel@mozilla.com Jeff Muizelaar], [mailto:birunthan@mohanathas.com Birunthan Mohanathas]
|group=dev-platform
|source_dirs=build/clang-plugin, tools/rewriting among other out of tree tools
|url=
|components=Core::Rewriting & Analysis
}}
{{Module
|name=storage
|description=Storage APIs with a SQLite backend
|owner=[mailto:mak77@bonardo.net Marco Bonardo]
|peers=[mailto:bugmail@asutherland.org Andrew Sutherland], [mailto:jvarga@mozilla.com Jan Varga]
|group=dev-platform
|source_dirs=db/sqlite3/, storage/
|url=http://developer.mozilla.org/en/docs/Storage
|components=Toolkit::Storage, Core::SQL
}}

{{Module
|name=String
|description=
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:jlebar@mozilla.com Justin Lebar]
|group=dev-tech-xpcom
|source_dirs=string/, xpcom/string/
|url=https://developer.mozilla.org/En/Mozilla_internal_string_guide
|components=Core::String
}}

{{Module
|name=Style System
|description=CSS style sheet handling; style data computation
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:cam@mcc.id.au Cameron McCormack]
|group=dev-tech-layout
|source_dirs=layout/style/
|url=https://wiki.mozilla.org/Gecko:Overview#Style_System
|components=Core::CSS Parsing and Computation
}}

{{Module
|name=SVG
|description=Scalable Vector Graphics
|owner=[mailto:jwatt@jwatt.org Jonathan Watt]
|peers=[mailto:longsonr@gmail.com Robert Longson], [mailto:robert@ocallahan.org Robert O'Callahan], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:birtles@gmail.com Brian Birtles]
|group=dev-tech-svg
|source_dirs=dom/svg/, layout/svg/, dom/smil/
|url=https://developer.mozilla.org/en-US/docs/Web/SVG
|components=Core::SVG
}}

{{Module
|name=Tamarin
|description=VM for ActionScript and JavaScript
|owner=Edwin Smith, [mailto:jodyer@adobe.com Jeff Dyer]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:stejohns@adobe.com Steven Johnson], [mailto:tierney@adobe.com Erik Tierney], [mailto:treilly@adobe.com Tom Reilly]
|group=dev-tech-js-engine
|source_dirs=js/tamarin
|url=http://www.mozilla.org/projects/tamarin/
http://wiki.mozilla.org/tamarin/
http://hg.mozilla.org/tamarin-central/
http://hg.mozilla.org/tamarin-tracing/
|components=Tamarin
}}

{{Module
|name=Test Harness
|description=In-tree test infrastructure and tools. Harnesses include, XPCShell, Mochitest (& Chrome), Reftest, JsREftest, Compiled Code Tests, Robocop, Mozmill, Marionette, Firefox UI Tests. Requests for new harnesses should go to Testing::General.
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:dbaron@dbaron.org David Baron] (reftest), [mailto:jwalden@mit.edu Jeff Walden] (httpd.js, jsreftest), Rob Campbell (mochitest, mochitest chrome, marionette), [mailto:jmaher@mozilla.com Joel Maher] (reftest, mochitest, jsreftest), [mailto:ctalbert@mozilla.com Clint Talbert] (reftest, compiled code, mozmill), [mailto:geoffbrown@mozilla.com Geoff Brown] (robocop), [mailto:hskupin@mozilla.com Henrik Skupin] (Marionette, Firefox UI tests), [mailto:ato@mozilla.com Andreas Tolfsen] (marionette), [mailto:jgriffin Jonathan Griffin] (marionette), [mailto:dburns@mozilla.com David Burns] (marionette) [mailto:dminor@mozilla.com Dan Minor], [mailto:mjzffr@gmail.com Maja Frydrychowicz] (Marionette, Firefox UI tests),

|group=dev-quality
|source_dirs=/testing
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::General, Testing::Mochitest, Testing::Mochitest Chrome, Testing::Marionette, Testing::Mozmill, Testing::Reftest, Testing::XPCShell Harness, Testing::httpd.js
}}

{{Module
|name=Testing Infrastructure
|description=Testing tools and infrastructure for Mozilla projects, harnesses for automated tests, stand-alone test tools. Talos, Graph Server, Mozbase, Pulse, WOO, Bughunter, SUTAgent, Eideticker
|owner=[mailto:jmaher@mozilla.com Joel Maher]
|peers=[mailto:bclary@bclary.com Bob Clary], [mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:ccooper@deadsquid.com Chris Cooper], [mailto:ctalbert@mozilla.com Clint Talbert], [mailto:robert@roberthelmer.com Robert Helmer], [mailto:jmaher@mozilla.com Joel Maher], Rob Campbell, [mailto:wlach@mozilla.com William Lachance], [mailto:jeads@mozilla.com Jonathan Eads], [mailto:jgriffin Jonathan Griffin], [mailto:bmoss@mozilla.com Bob Moss], [mailto:mcote@mozilla.com Mark Côté]
|group=dev-quality
|source_dirs=testing/, tools/httptester/, tools/page-loader/, tools/test-harness/, tools/tests/, tools/testserver/, tools/testy/
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::Infrastructure
}}

{{Module
|name=JS Marionette
|description=NodeJS test harness, marionette client, and other utilities for running marionette tests (submodule of Test Infrastructure)
|owner=[mailto:jlal@mozilla.com James Lal] <lightsofapollo>, [mailto:gaye@mozilla.com Gareth Aye] <gaye>
|peers=[mailto:aus@mozilla.com Ghislain "Aus" Lacroix] <auswerk>
|source_dirs=gaia/tests/jsmarionette
|components=Testing::JSMarionette
|group=dev-gaia
}}

{{Module
|name=XPCShell Test Harness
|description=The XPCShell Harness
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:jmaher@mozilla.com Joel Maher]
|source_dirs=testing/xpcshell
|components=Testing::XPCShell Harness
}}

{{Module
|name=Update Service
|description=server code for Mozilla Update services (aus, addons, pfs)
|owner=Mike Morgan
|peers=[mailto:jscott@mozilla.com Justin Scott], [mailto:shaver@mozilla.org Mike Shaver], [mailto:wclouser@mozilla.com Will Clouser]
|group=dev-amo
|source_dirs=webtools/addons/, webtools/aus/, webtools/update/
|url=http://wiki.mozilla.org/wiki/AMO
|components=AUS::Administration, AUS::Systems
}}

{{Module
|name=View System
|description=The View Manager is responsible for handling "heavyweight" rendering (some clipping, compositing) and event handling tasks.
|owner=[mailto:mstange@themasta.com Markus Stange]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dbaron@dbaron.org David Baron]
|group=dev-tech-layout
|source_dirs=view/
|url=
|components=Core::Layout: View Rendering
}}

{{Module
|name=Web Audio
|description=Support for the W3C Web Audio API specification.
|owner=[mailto:padenot@mozilla.com Paul Adenot]
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:karlt+@karlt.net Karl Tomlinson]
|group=dev-platform
|source_dirs=dom/media/webaudio
|url=https://wiki.mozilla.org/Web_Audio_API
|components=Core::Web Audio
}}

{{Module
|name=Web Painting
|description=painting, display lists, and layer construction
|owner=[mailto:matt.woodrow@gmail.com Matt Woodrow]
|peers=[mailto:robert@ocallahan.org Robert O'Callahan], [mailto:dbaron@dbaron.org David Baron], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:mstange@themasta.com Markus Stange]
|group=dev-tech-layout
|source_dirs= layout/painting, the display list and layer related methods on nsIFrame and its subclasses
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout: Web Painting
}}

{{Module
|name=WebRTC
|description=WebRTC is responsible for realtime audio and video communication, as well as related issues like low-level camera and microphone access
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:bcampen@mozilla.com Byron Campen] [mailto:abr@mozilla.com Adam Roach]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=N/A (see submodules "WebRTC Media" and "WebRTC Signaling")
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC
}}

{{Module
|name=Widget
|description=
|owner=[mailto:vladimir@pobox.com Vladimir Vukicevic]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|peersemeritus=[mailto:pavlov@pavlov.net Stuart Parmenter],
|group=dev-platform
|source_dirs=widget/, widget/xpwidgets/
|url=
|components=Core::Drag and Drop, Core::Widget, Core::Printing: Setup
}}

{{Module
|name=Widget - Android
|description=The Android Port
|owner=[mailto:blassey.bugs@lassey.us Brad Lassey]
|peers=[mailto:jwillcox@mozilla.com James Willcox]
|group=dev-platforms-mobile
|source_dirs=widget/android/, embedding/android
|url=
|components=Core::Widget: Android
}}

{{Module
|name=Widget - GTK
|description=supported X widgetry and gfx
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|ownersemeritus=[mailto:robert@ocallahan.org Robert O'Callahan]
|group=dev-platform
|source_dirs=widget/gtk/, widget/gtk2/, widget/gtksuperwin/, widget/gtkxtbin/
|url=http://www.mozilla.org/unix/, http://www.gtk.org, http://www.mozilla.org/ports/gtk/
|components=Core::Widget: Gtk
}}

{{Module
|name=Widget - OS X
|description= Gecko's OS X compatibility layer.
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:joshmoz@gmail.com Josh Aas], [mailto:bgirard@mozilla.com Benoit Girard], [mailto:spohl@mozilla.com Stephen Pohl], [mailto:smichaud@pobox.com Steven Michaud]
|group=dev-platform
|source_dirs=widget/cocoa/
|url=
|components=Core::Widget: Cocoa
}}

{{Module
|name=Widget - Windows
|description=Windows widgets and desktop integration
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook], [mailto:vladimir@pobox.com Vladimir Vukicevic], [mailto:jmathies@mozilla.com Jim Mathies]
|peersemeritus=[mailto:blassey@mozilla.com Brad Lassey], [mailto:netzen@gmail.com Brian Bondy], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:doug.turner@gmail.com Doug Turner], [mailto:timeless@mozdev.org Josh 'timeless' Soref], [mailto:robarnold@cmu.edu Rob Arnold]
|group=dev-platform
|source_dirs=widget/windows/
|url=
|components=Core::Widget: Win32
}}

{{Module
|name=XBL
|description=eXtensible Binding Language
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:jonas@sicking.cc Jonas Sicking]
|ownersemeritus=[mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xbl
|source_dirs=dom/xbl/
|url=http://www.mozilla.org/projects/xbl/
|components=Core::XBL
}}

{{Module
|name=XML
|description=XML in Mozilla, including XML, XHTML, Namespaces in XML, Associating Style Sheets with XML Documents, XML Linking and XML Extras. XML-related things that are not covered by more specific projects.
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:jstenback@gmail.com Johnny Stenback]
|group=dev-tech-xml
|source_dirs=dom/xml/, extensions/xmlextras/, parser/expat/
|url=http://www.mozilla.org/newlayout/xml/
|components=Core::XML
}}

{{Module
|name=XPApps
|description=Cross-Platform Applications, mostly Navigator front end and application shell.
|owner=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|peers=[mailto:dean_tessman@hotmail.com Dean Tessman], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-apps-seamonkey
|source_dirs=xpfe/
|url=http://www.mozilla.org/xpapps/
|components=
}}

{{Module
|name=XPCOM
|description=The cross-platform object model and core data structures.
|owner=[https://mozillians.org/en-US/u/froydnj/ Nathan Froyd]
|peers=[https://mozillians.org/en-US/u/bsmedberg/ Benjamin Smedberg], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[https://mozillians.org/en-US/u/dougt/ Doug Turner]
|group=dev-platform
|source_dirs=startupcache/, xpcom/%, xpcom/base/, xpcom/build/, xpcom/components/, xpcom/ds/, xpcom/glue/, xpcom/proxy/, xpcom/sample/, xpcom/stub/, xpcom/tests/, xpcom/threads/, xpcom/tools/, xpcom/windbgdlg/
|url=http://developer.mozilla.org/en/XPCOM
|components=Core::XPCOM
}}

{{Module
|name=XPConnect
|description=Deep Magic
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:gkrizsanits@mozilla.com Gabor Krizsanits], [mailto:amccreight@mozilla.com Andrew McCreight]
|peersemeritus=[mailto:gal@uci.edu Andreas Gal], [mailto:jstenback@gmail.com Johnny Stenback]
|group=
|source_dirs=js/xpconnect/
|url=
|components=Core::XPConnect
}}

{{Module
|name=XPIDL
|description=Cross-platform IDL compiler; produces .h C++ header files and .xpt runtime type description files from .idl interface description files.
|owner=[mailto:me@kylehuey.com Kyle Huey]
|peersemeritus=[mailto:shaver@mozilla.org Mike Shaver], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-tech-xpcom
|source_dirs=xpcom/typelib/
|url=http://www.mozilla.org/scriptable/xpidl
http://www.mozilla.org/scriptable
|components=
}}

{{Module
|name=XPInstall
|description=
|owner=[mailto:dveditz@mozilla.com Dan Veditz]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|group=dev-tech-xpinstall
|source_dirs=xpinstall/
|url=
|components=Core::Installer: XPInstall Engine
}}

{{Module
|name=xptcall
|description=XPTCall - platform-specific assembly for calling and implementing arbitrary XPCOM interfaces.
|owner=
|ownersemeritus=[mailto:timeless@mozdev.org Josh 'timeless' Soref]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:shaver@mozilla.org Mike Shaver]
|group=dev-xpcom
|source_dirs=xpcom/reflect/xptcall/
|url=http://www.mozilla.org/scriptable/xptcall-faq.html
|components=
}}

{{Module
|name=XPToolkit
|description=Cross-platform user interface toolkit
|owner=
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:Jan.Varga@gmail.com Jan Varga]
|group=dev-tech-xul
|source_dirs=dom/xul/, layout/xul/
|url=http://www.mozilla.org/xpfe/
|components=Core::XP Toolkit/Widgets: Menus, Core::XP Toolkit/Widgets: XUL
}}

{{Module
|name=XSLT Processor
|description=XSLT transformations processor
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:axel@pike.org Axel Hecht], [mailto:erahm@mozilla.com Eric Rahm]
|peersemeritus=[mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xslt
|source_dirs=dom/xslt/
|url=http://www.mozilla.org/projects/xslt/, http://www.w3.org/TR/xslt.html
|components=Core::XSLT
}}

{{Module
|name=XTF
|description=eXtensible Tag Framework
|owner=
|peers=[mailto:alex@croczilla.com alex@croczilla.com], [mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xbl
|source_dirs=content/xtf/, layout/xtf/
|url=http://www.croczilla.com/bits_and_pieces/xtf/
|components=Core::XTF
}}

{{Module
|name=Sandboxing
|description=Cross platform sandboxing
|owner=[mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|peers=[mailto:bowen@mozilla.com Bob Owen], [mailto:aklotz@mozilla.com Aaron Klotz], [https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes], [mailto:gDestuynder@mozilla.com Guillaume Destuynder], [mailto:jld@mozilla.com Jed Davis]
|group=dev-platform
|source_dirs=security/sandbox
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Windows
|description=Sandboxing for the Windows platform
|owner=[mailto:bowen@mozilla.com Bob Owen]
|peers=[mailto:netzen@gmail.com Brian Bondy], [mailto:aklotz@mozilla.com Aaron Klotz], [https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes], [mailto:jimm@mozilla.com Jim Mathies]
|group=dev-platform
|source_dirs=security/sandbox/win
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - OSX
|description=Sandboxing for the OSX platform
|owner=[mailto:haftandilian@mozilla.com Haik Aftandilian]
|peers=
|group=dev-platform
|source_dirs=security/sandbox/mac
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Linux & B2G
|description=Sandboxing for the Linux & B2G platforms
|owner=[mailto:jhector@mozilla.com Julian Hector]
|peers=[mailto:jld@mozilla.com Jed Davis] [mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|group=dev-platform
|source_dirs=security/sandbox/linux
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

===Submodules===
{{Module
|name=Build Config - Fennec
|description=Submodule of the build config covering Fennec's build system in mobile/android.
|owner=[mailto:nalexander@mozilla.com Nicholas Alexander]
|peers=Same as Build Config
|group=dev-builds
|components=Core::Build Config
}}

{{Module
|name=WebRTC Media
|description=Submodule of WebRTC responsible for access to media input devices (microphones, cameras, screen capture), as well as realtime audiovisual codecs and packetization.
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:pkerr@mozilla.com Paul Kerr], [mailto:jib@mozilla.com Jan-Ivar Bruaroey]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=/media/webrtc, /dom/media/webrtc
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Audio/Video)
}}

{{Module
|name=WebRTC Signaling
|description=Submodule of WebRTC responsible for implementation of PeerConnection API, WebRTC identity, and SDP/JSEP handling
|owner=[mailto:bcampen@mozilla.com Byron Campen]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:abr@mozilla.com Adam Roach], [mailto:rjesup@mozilla.com Randell Jesup], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|peersemeritus=[mailto:ehugg@cisco.com Ethan Hugg]
|group=dev-media
|source_dirs=/media/webrtc/signaling/
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Signaling)
}}

<noinclude>

===Unassigned Bugzilla Components===

The following Bugzilla components in the Core project have not been assigned to a module (this list is not exhaustive):

<pre>
Core::File Handling
Core::Find Backend
Core::Gecko Profiler
Core::General
Core::HTML: Form Submission
Core::History: Global
Core::Image Blocking
Core::JavaScript Debugging APIs
Core::Localization
Core::Nanojit
Core::Networking: Domain Lists
Core::Print Preview
Core::Printing: Output
Core::Printing: Setup
Core::Profile: BackEnd
Core::Profile: Migration
Core::Profile: Roaming
Core::QuickLaunch (AKA turbo mode)
Core::Rewriting and Analysis
Core::Selection
Core::Serializers
Core::Spelling checker
Core::Tracking
Core::Web Services
Core::WebDAV
Core::Widget: OS/2
Core::Widget: Photon
Core::X-remote
Core::XForms
Core::XUL
</pre>
</noinclude>

Modules/Core

2016-08-11T15:04:24Z

Surkov.alexander:

<noinclude>
'''Only module owners may edit this page.'''

They may:

* update any information about their module except the name of the owner
* add or remove sub-modules
* change the owner of a sub-module
* add emeritus owners or peers

Other changes, including changes of module owner or addition/removal of modules, must be agreed with the Module Ownership Module group, probably via a discussion in [https://www.mozilla.org/about/forums/#governance mozilla.governance].
</noinclude>
{{Module
|name=Accessibility
|description=Support for platform accessibility APIs. Accessibility APIs are used by 3rd party software like screen readers, screen magnifiers, and voice dictation software, which need information about document content and UI controls, as well as important events like changes of focus.
|owner=[mailto:surkov.alexander@gmail.com Alexander Surkov]
|peers=[mailto:bolterbugz@gmail.com David Bolter], [mailto:trev.saunders@gmail.com Trevor Saunders], [mailto:marco.zehe@googlemail.com Marco Zehe]
|ownersemeritus=[mailto:aaron@moonset.net. Aaron Leventhal]
|peersemeritus=[mailto:ginn.chen@oracle.com Ginn Chen], Evan Yan
|group=dev-accessibility
|source_dirs=accessible/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=Browser WebAPI
|description=Web API for rendering apps, browser windows and widgets.
|owner=[mailto:kchen@mozilla.com Kan-Ru Chen]
|peers=[mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:fabrice@mozilla.com Fabrice Desré]
|group=dev-webapi
|source_dirs=dom/browser-element/
|url=
|components=Core::DOM
}}

{{Module
|name=Build and Release Tools
|description=Tools related to build and release automation and configuration of release builds.
|owner=[mailto:nthomas@mozilla.com Nick Thomas]
|peers=[mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:coop@mozilla.com Chris Cooper]
|group=release-engineering
|source_dirs=browser/config/mozconfigs/, mobile/android/config/mozconfigs/, xulrunner/config/mozconfigs/, b2g/config/, tools/update-packaging/
|url=https://wiki.mozilla.org/ReleaseEngineering
|components=Release Engineering::*
}}

{{Module
|name=Build Config
|description=The build system for Gecko and several mozilla.org hosted Gecko-based applications.
|owner=[mailto:gps@mozilla.com Gregory Szorc] (:gps)
|peers=[mailto:mh@glandium.org Mike Hommey] (:glandium), [mailto:mshal@mozilla.com Mike Shal] (:mshal), [mailto:ted@mielczarek.org Ted Mielczarek] (:ted), [mailto:cmanchester@mozilla.com Chris Manchester](:chmanchester)
|ownersemeritus=Ted Mielczarek (2008-[https://blog.mozilla.org/ted/2013/03/07/gregory-szorc-is-now-the-build-config-module-owner/ 2013]), Benjamin Smedberg (???-[http://benjamin.smedbergs.us/blog/2008-04-30/more-changing-of-the-guard-ted-mielczarek/ 2008]),
|group=dev-builds
|source_dirs=build/, config/, python/mozbuild, tools/cross-commit, tools/cvs2hg-import.py, tools/cvsmgmt/, tools/elf-dynstr-gc/, tools/trees.pl, browser/config/mozconfigs/, mobile/config/mozconfigs/, xulrunner/config/mozconfigs/
|url=http://www.mozilla.org/build/
|components=Core::Build Config
}}

{{Module
|name=Code Analysis and Debugging Tools
|description=Tools for debugging Mozilla code or for analyzing speed, memory use, and other characteristics of it.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=
|group=dev-performance
|source_dirs=tools/codesighs/, tools/debug/, tools/dreftool/, tools/dumpdeps/, tools/footprint/, tools/jprof/, tools/leaky/, tools/memory/, tools/module-deps/, tools/performance/, tools/post_compile/, tools/preloader/, tools/rb/, tools/reorder/, tools/trace-malloc/, tools/uuiddeps/,
|url=
|components=
}}

{{Module
|name=Content HTTP Headers
|description=HTTP headers related to content, e.g. User-Agent, Content-Type, Accept. (Transport-related headers are the responsibility of the Necko module owner.)
|owner=[mailto:gerv@mozilla.org Gervase Markham]
|peers=[mailto:lmandel@mozilla.com Lawrence Mandel]
|group=dev-platform
|source_dirs=
|url=https://developer.mozilla.org/en/Gecko_user_agent_string_reference
|components=Core::Networking: HTTP
}}

{{Module
|name=Content Security
|description=Native content-based security features, including: Content Security Policy (CSP), Mixed Content Blocker (MCB), Subresource Integrity (SRI) and CORS.
|owner=[mailto:ckerschbaumer@mozilla.com Christoph Kerschbaumer]
|peers=[mailto:francois@mozilla.com François Marier], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:tvyas@mozilla.com Tanvi Vyas], [mailto:dveditz@mozilla.com Dan Veditz], [mailto:mozilla@sidstamm.com Sid Stamm]
|group=dev-security
|source_dirs=dom/security
|components=Core::DOM: Security
}}

{{Module
|name=Cookies and Permissions
|description=
|owner=Monica Chew
|peers=[mailto:josh@joshmatthews.com Josh Matthews], [mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:mconnor@steelgryphon.com Mike Connor], [mailto:dwitte@gmail.com Dan Witte], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sdwilsh@shawnwilsher.com Shawn Wilsher (ping on irc)]
|group=dev-tech-network
|source_dirs=extensions/cookie/, netwerk/cookie/
|url=
|components=Core::Networking: Cookies
}}
{{Module
|name=Cycle Collector
|description=Code to break and collect objects within reference cycles
|owner=[https://mozillians.org/en-US/u/mccr8/ Andrew McCreight]
|peers=Peter Van der Beken, Olli Pettay, David Baron
|source_dirs=xpcom/base/nsCycleCollector.* and some support headers
|components=Core::XPCOM
|group=dev-platform
}}
{{Module
|name=docshell
|description=
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky]
|peers=[mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:jst@mozilla.org Johnny Stenback], [mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:justin.lebar@gmail.com Justin Lebar]
|group=dev-tech-layout
|source_dirs=docshell/, uriloader/
|url=
|components=Core::Document Navigation
}}

{{Module
|name=Device Storage
|description=Support for the device storage API
|owner=[https://mozillians.org/u/dhylands/ Dave Hylands] (:dhylands), [mailto:jvarga@mozilla.com Jan Varga] (:janv)
|peers=
|ownersemeritus=[mailto:doug.turner@gmail.com Doug Turner] (:dougt)
|group=dev-tech-dom
|source_dirs=dom/devicestorage/, dom/interfaces/devicestorage/
|url=https://developer.mozilla.org/en-US/docs/WebAPI/Device_Storage
|components=Core::DOM: Device Interfaces
}}

{{Module
|name=Document Object Model
|description=
|owner=[mailto:jst@mozilla.org Johnny Stenback], [mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:Olli.Pettay@helsinki.fi Olli Pettay], [mailto:bent@mozilla.com Ben Turner], [mailto:mounir@lamouri.fr Mounir Lamouri (still active, but slower to respond than previously)], [mailto:me@kylehuey.com Kyle Huey], [mailto:justin.lebar@gmail.com Justin Lebar], [mailto:hsivonen@iki.fi Henri Sivonen], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:baku@mozilla.com Andrea Marchesini],
[mailto:ehsan@mozilla.com Ehsan Akhgari], [mailto:bkelly@mozilla.com Ben Kelly]
|group=dev-tech-dom
|source_dirs=dom/*, except directories covered by other modules
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM, Core::DOM: CSS Object Model, Core::DOM: Core & HTML
}}

{{Module
|name=Event Handling
|description=DOM Events and Event Handling
|owner=[mailto:olli@pettay.fi Olli Pettay], [mailto:masayuki@d-toybox.com Masayuki Nakano]
|group=dev-platform
|source_dirs=dom/events and event handling related code elsewhere
|url=http://developer.mozilla.org/en/docs/DOM
|components=Core::DOM: Events, Core::Event Handling
}}

{{Module
|name=Web Workers
|description=
|owner=[mailto:bent@mozilla.com Ben Turner]
|peers=[mailto:mrbkap@mozilla.com Blake Kaplan], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey]
|group=dev-platform
|source_dirs=dom/workers/
|url=https://developer.mozilla.org/En/Using_web_workers
|components=Core::DOM: Workers
}}

{{Module
|name=IndexedDB
|description=
|owner=[mailto:bent@mozilla.com Ben Turner]
|peers=[mailto:jonas@sicking.cc Jonas Sicking], [mailto:me@kylehuey.com Kyle Huey], [mailto:jvarga@mozilla.com Jan Varga]
|group=dev-platform
|source_dirs=dom/indexedDB/
|url=https://developer.mozilla.org/en/IndexedDB
|components=Core::DOM: IndexedDB
}}

{{Module
|name=Editor
|description=
|owner=
|peers=
|ownersemeritus=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|group=dev-platform
|source_dirs=editor/
|url=http://www.mozilla.org/editor/
|components=Core::Editor
}}

{{Module
|name=Embedding
|description=
|owner=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jst@mozilla.org Johnny Stenback]
|group=dev-embedding
|source_dirs=embedding/
|url=
|components=Core::Embedding: APIs, Core::Embedding: ActiveX Wrapper, Core::Embedding: GRE Core, Core::Embedding: GTK Widget, Core::Embedding: MFC Embed, Core::Embedding: Mac, Core::Embedding: Packaging
}}

{{Module
|name=Find As You Type
|description=Find As You Type (formerly called Type Ahead Find) is a feature that allows quick web page navigation when you type a succession of characters in the body of the displayed page (not in an edit box of or drop down list). Currently seeks new owner.
|owner=
|peers=
|group=dev-accessibility
|source_dirs=extensions/typeaheadfind/
|url=http://www.mozilla.org/access/type-ahead/
|components=
}}

{{Module
|name=Geolocation
|description=Implementation of the Geolocation W3C Spec, location provider apis, and wifi scanning code.
|owner=[mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:josh@joshmatthews.net Josh Matthews], [mailto:kchen@mozilla.com Kan-Ru Chen], Garvan Keeley
|group=dev-tech-dom
|source_dirs=dom/geolocation, dom/system/, netwerk/wifi
|url=https://developer.mozilla.org/En/Using_geolocation
|components=Core::Geolocation
}}

{{Module
|name=Global Key Bindings
|description=Global hot keys in Mozilla for the browser, editor, mail-news and widgets. Does not include underlined menu accelerators and the like, as those are part of i18n.
|owner=Aaron Leventhal
|peers=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|group=dev-accessibility
|source_dirs=dom/xbl/builtin/
|url=http://www.mozilla.org/projects/ui/accessibility/mozkeyintro.html
|components=Core::Keyboard: Navigation
}}

{{Module
|name=Graphics
|description=Mozilla graphics API
|owner=[mailto:jrmuizel@mozilla.com Jeff Muizelaar](Thebes, QCMS, YCbCr, Cairo/Pixman, Regions, OS X, Other), [mailto:roc+@cs.cmu.edu Robert O'Callahan]
|peers=[mailto:jdrew@mozilla.com Joe Drew], [mailto:vladimir@pobox.com Vladimir Vukicevic], [mailto:bas.schouten@live.nl Bas Schouten](Layers, Windows), [mailto:bjacob@mozilla.com Benoit Jacob](gfx/gl), [mailto:bgirard@mozilla.com Benoit Girard](Compositor, Performance), [mailto:ajuma.bugzilla@alijuma.com Ali Juma], [mailto:jgilbert@mozilla.com Jeff Gilbert](WebGL, ANGLE), [mailto:george@mozilla.com George Wright](Canvas2D, Skia), [mailto:mwoodrow@mozilla.com Matt Woodrow](Layers API), [mailto:jdaggett@mozilla.com John Daggett](text/fonts), [mailto:jfkthame@googlemail.com Jonathan Kew](text/fonts), [mailto:nsilva@mozilla.com Nicolas Silva](MozSurface), [mailto:ncameron@mozilla.com Nick Cameron], [mailto:sikeda@mozilla.com Sotaro Ikeda](B2G), [mailto:snorp@mozilla.com James Willcox](Android), [mailto:clord@mozilla.com Christopher Lord], [mailto:mstange@themasta.com Markus Stange](OS X)
|group=dev-platform
|source_dirs=gfx/, dom/canvas/
|url=https://wiki.mozilla.org/Platform/GFX https://wiki.mozilla.org/Gecko:Layers https://wiki.mozilla.org/Gecko:2DGraphicsSketch
|components=Core::Graphics, Core::Graphics: Layers, Core::Graphics: Text, Core::GFX: Color Management, Core::Canvas: 2D, Core::Canvas: WebGL
}}

{{Module
|name=APZ (Graphics submodule)
|description=Asynchronous panning and zooming
|owner=[mailto:kgupta@mozilla.com Kartikaya Gupta]
|peers=[mailto:bballo@mozilla.com Botond Ballo], [mailto:tnikkel@mozilla.com Timothy Nikkel], [mailto:dvander@mozilla.com David Anderson], [mailto:mstange@mozilla.com Markus Stange]
|group=dev-platform
|source=gfx/layers/apz
|url=https://wiki.mozilla.org/Platform/GFX/APZ
|components=Core::Panning and Zooming
}}

{{Module
|name=Moz2D (Graphics submodule)
|description=Platform independent 2D graphics API
|owner=[mailto:bschouten@mozilla.com Bas Schouten]
|peers=[mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:gwright@mozilla.com George Wright], [mailto:jwatt@mozilla.com Jonathan Watt]
|group=dev-platform
|source=gfx/2d
|url=https://wiki.mozilla.org/Platform/GFX/Moz2D
|components=Core::Graphics
}}

{{Module
|name=GTK Embedding Widget
|description=Gtk Widget for embedding Mozilla into Gtk applications
|owner=Marco Pesenti Gritti
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:doug.turner@gmail.com Doug Turner]
|group=dev-embedding
|source_dirs=
|url=
|components=Core::Embedding: GTK Widget
}}

{{Module
|name=Legacy HTML Parser
|description=
|owner=[mailto:mrbkap@gmail.com Blake Kaplan]
|peers=[mailto:dbaron@dbaron.org David Baron], [mailto:jst@mozilla.org Johnny Stenback], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:rbs@maths.uq.edu.au rbs@maths.uq.edu.au]
|group=dev-tech-dom
|source_dirs=parser/htmlparser
|url=http://www.mozilla.org/newlayout/doc/parser.html
|components=Core::HTML: Parser
}}

{{Module
|name=HAL
|description=Hardware Abstraction Layer
|owner=[https://mozillians.org/u/dhylands/ Dave Hylands]
|peers=[mailto:gsvelto@mozilla.com Gabriele Svelto]
|group=dev-platform
|source_dirs=hal/
|components=Core::Hardware Abstraction Layer (HAL)
}}

{{Module
|name=HTML Parser
|description=The HTML Parser transforms HTML source code into a DOM. It conforms to the HTML specification, and is mostly translated automatically from Java to C++.
|owner=[mailto:hsivonen@iki.fi Henri Sivonen]
|peers=
|group=dev-tech-dom
|source_dirs=parser/html
|url=http://about.validator.nu/
|components=Core::HTML: Parser
}}

{{Module
|name=I18N Library
|description=
|owner=[mailto:jshin1987@gmail.com Jungshik Shin], [mailto:smontagu@smontagu.org Simon Montagu]
|peers=[mailto:VYV03354@nifty.ne.jp Masatoshi Kimura]
|group=dev-i18n
|source_dirs=intl/
|url=http://mozilla.org/projects/intl/index.html
|components=Core::Internationalization
}}

{{Module
|name=ImageLib
|description=
|owner=[mailto:seth@mozilla.com Seth Fowler]
|peers=[mailto:netzen@gmail.com Brian Bondy], [mailto:jmuizelaar@mozilla.com Jeff Muizelaar], [mailto:jlebar@mozilla.com Justin Lebar], [mailto:tnikkel@gmail.com Timothy Nikkel]
|group=dev-platform
|source_dirs=media/libjpeg/, media/libpng/, image/, modules/zlib/
|url=
|components=Core::ImageLib
}}

{{Module
|name=IPC
|description=Message-passing between threads and processes
|owner=[mailto:wmccloskey@mozilla.com Bill McCloskey]
|peers=[mailto:danderson@mozilla.com David Anderson], [mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:bent.mozilla@gmail.com Ben Turner], [mailto:jld@mozilla.com Jed Davis]
|group=dev-platform
|source_dirs=ipc/glue/, ipc/ipdl/, ipc/chromium/
|url=
|components=Core::IPC}}

{{Module
|name=JavaScript
|description=JavaScript engine (SpiderMonkey)
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:jdemooij@mozilla.com Jan de Mooij], [mailto:wmccloskey@mozilla.com Bill McCloskey], [mailto:nnethercote@mozilla.com Nick Nethercote], [mailto:jwalden@mit.edu Jeff Walden], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:evilpies@gmail.com Tom Schuster], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:till@tillschneidereit.net Till Schneidereit], [mailto:efaust@mozilla.com Eric Faust], [mailto:nfitzgerald@mozilla.com Nick Fitzgerald], [mailto:luke@mozilla.com Luke Wagner], [mailto:arai.unmht@gmail.com Tooru Fujisawa], [mailto:sunfish@mozilla.com Dan Gohman], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley], [mailto:nmatsakis@mozilla.com Niko Matsakis], [mailto:ejpbruel@mozilla.com Eddy Bruel], [mailto:danderson@mozilla.com David Anderson], [mailto:igor@mir2.org Igor Bukanov], [mailto:brendan@mozilla.org Brendan Eich], Andreas Gal
|group=dev-tech-js-engine
|source_dirs=js/src
|url=http://www.mozilla.org/js/spidermonkey,
http://developer.mozilla.org/en/docs/About_JavaScript
|components=Core::JavaScript Engine
}}

{{Module
|name=JavaScript JIT
|description=JavaScript engine's JIT compilers (IonMonkey, Baseline)
|owner=[mailto:jdemooij@mozilla.com Jan de Mooij]
|peers=[mailto:danderson@mozilla.com David Anderson], [mailto:bbouvier@mozilla.com Benjamin Bouvier], [mailto:shu@mozilla.com Shu-yu Guo], [mailto:bhackett1024@gmail.com Brian Hackett], [mailto:nicolas.b.pierron@mozilla.com Nicolas Pierron], [mailto:evilpies@gmail.com Tom Schuster], [mailto:sstangl@mozilla.com Sean Stangl], [mailto:hv1989@gmail.com Hannes Verschore], [mailto:kvijayan@mozilla.com Kannan Vijayan], [mailto:luke@mozilla.com Luke Wagner]
|group=dev-tech-js-engine-internals
|source_dirs=js/src/jit
|url=http://www.mozilla.org/js/spidermonkey
|components=Core::JavaScript Engine: JIT
}}

{{Module
|name=JavaScript Debugger Backend
|description=JavaScript debugging hooks
|owner=[mailto:timeless@mozdev.org Josh 'timeless' Soref]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:rginda@hacksrus.com Rob Ginda]
|group=dev-apps-js-debugger
|source_dirs=js/jsd/
|url=http://www.mozilla.org/js/jsd
|components=Other Applications::Venkman JS Debugger
}}

{{Module
|name=jsat
|description=Javascript screen reader that is used in Android and B2G
|owner=[mailto:eitan@monotonous.org Eitan Isaacson]
|peers=[mailto:yzenevich@mozilla.com Yura Zenevich]
|group=dev-accessibility
|source_dirs=accessible/jsat/
|url=http://www.mozilla.org/access/
|components=Core::Disability Access APIs
}}

{{Module
|name=js-ctypes
|description=A foreign function interface which allows privileged JS code to interact with binary code without using XPCOM/XPConnect.
|owner=[mailto:jorendorff@mozilla.com Jason Orendorff]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:bobbyholley@gmail.com Bobby Holley]
|group=dev-tech-js-engine
|source_dirs=js/src/ctypes/
|url=https://wiki.mozilla.org/JSctypes
|components=Core::js-ctypes
}}

{{Module
|name=js-tests
|description=JavaScript test suite
|owner=[mailto:bclary@bclary.com Bob Clary]
|peers=
|group=dev-tech-js-engine
|source_dirs=js/tests/
|url=http://www.mozilla.org/js/tests/library.html
|components=
}}

{{Module
|name=Layout Engine
|description=rendering tree construction, layout (reflow), painting, etc.
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:roc+@cs.cmu.edu Robert O'Callahan], [mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:jfkthame@gmail.com Jonathan Kew], [mailto:tnikkel@gmail.com Timothy Nikkel], [mailto:matt.woodrow@gmail.com Matt Woodrow], [mailto:xidorn+moz@upsuper.org Xidorn Quan]
|group=dev-tech-layout
|source_dirs=layout/%, layout/base/, layout/build/, layout/doc/, layout/forms/, layout/generic/, layout/html/, layout/macbuild/, layout/printing/, layout/tables/, layout/tools/
|url=http://mozilla.org/newlayout/doc/ ,
http://lxr.mozilla.org/mozilla/source/layout/doc/
|components=Core::Layout, Core::Layout: Block and Inline, Core::Layout: Floats, Core::Layout: Form Controls, Core::Layout: HTML Frames, Core::Layout: Images, Core::Layout: Misc Code, Core::Layout: R & A Pos, Core::Layout: Tables, Core::Layout: Text, Core::Layout: View Rendering, Core::Print Preview, Core::Printing: Output
}}

{{Module
|name=libjar
|description=The JAR handling code (protocol handler, stream implementation, and zipreader/zipwriter).
|owner=[mailto:mwu@mozilla.com Michael Wu]
|peers=[mailto:aklotz@mozilla.com Aaron Klotz]
|group=dev-platform
|source_dirs=modules/libjar
|url=
|components=
}}

{{Module
|name=MathML
|description=MathML is a low-level specification for describing mathematics which provides a foundation for the inclusion of mathematical expressions in Web pages.
|owner=[mailto:karlt+@karlt.net Karl Tomlinson]
|peers=[mailto:roc+@cs.cmu.edu Robert O'Callahan]
|group=dev-tech-mathml
|source_dirs=layout/mathml/
|url=http://www.mozilla.org/projects/mathml/
|components=Core::MathML
}}

{{Module
|name=Media Playback
|description=HTML Media APIs, including Media Source Extensions and non-MSE video/audio element playback, and Encrypted Media Extensions. (WebRTC and WebAudio not included).
|owner=[mailto:cpearce@mozilla.com Chris Pearce]
|peers=[mailto:ajones@mozilla.com Anthony Jones], [mailto:kinetik@flim.org Matthew Gregan], [mailto:eflores@mozilla.com Edwin Flores], [mailto:jyavenard@mozilla.com Jean-Yves Avenard], [mailto:gsquelart@mozilla.com Gerald Squelart], [mailto:rgiles@mozilla.com Ralph Giles], [mailto:jwwang@mozilla.com JW Wang]
|group=dev-media
|source_dirs=dom/media, media/gmp-clearkey/, media/libcubeb/, media/libnestegg/, media/libogg/, media/libopus/, media/libstagefright/, media/libtheora/, media/libtremor/, media/libvorbis/, media/libvpx/, media/omx-plugin/, media/rlz/
|url=
|components=Core::Audio/Video
}}

{{Module
|name=Media Transport
|description=Pluggable transport for real-time media
|owner=[mailto:ekr@rtfm.com Eric Rescorla]
|peers=[mailto:bcampen@mozilla.com Byron Campen], [mailto:abr@mozilla.com Adam Roach]
|group=dev-media
|source_dirs=media/mtransport
|url=
|components=Core::WebRTC::Networking
}}

{{Module
|name=Memory Allocator
|description=Most things related to memory allocation in Gecko, including jemalloc, replace-malloc, DMD (dark matter detector), logalloc, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:n.nethercote@gmail.com Nicholas Nethercote]
|group=dev-platform
|source_dirs=memory/
|components=Core::DMD, Core::jemalloc
}}

{{Module
|name=mfbt
|description=mfbt is a collection of headers, macros, data structures, methods, and other functionality available for use and reuse throughout all Mozilla code (including SpiderMonkey and Gecko more broadly).
|owner=[mailto:jwalden@mit.edu Jeff Walden]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd], [mailto:Ms2ger@gmail.com Ms2ger], [mailto:mh+mozilla@glandium.org Mike Hommey]
|group=dev-platform
|source_dirs=mfbt/
|url=
|components=Core::MFBT
}}

{{Module
|name=mozApps API & UI
|description=Implementation of the navigator.mozApps API
|owner=[mailto:fabrice@mozilla.com Fabrice Desré], [mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:myk@mozilla.org Myk Melez], [mailto:mar.castelluccio@studenti.unina.it Marco Castelluccio], [mailto:ferjmoreno@gmail.com Fernando Jiménez]
|group=dev-webapi
|source_dirs=dom/apps/, dom/interfaces/apps, product specific files implementing UI hooks.
|url=
|components=Core::DOM: Apps
}}

{{Module
|name=Mozglue
|description=Glue library containing various low-level functionality, including a dynamic linker for Android, a DLL block list for Windows, etc.
|owner=[mailto:mh+mozilla@glandium.org Mike Hommey]
|peers=[mailto:froydnj@mozilla.com Nathan Froyd] (mozglue/linker), [mailto:kgupta@mozilla.com Kartikaya Gupta] (mozglue/android), [mailto:nchen@mozilla.com Jim Chen] (mozglue/android)
|group=dev-platform
|source_dirs=mozglue/
|components=Core::mozglue
}}

{{Module
|name=mozilla-toplevel
|description=The top level directory for the mozilla tree.
|owner=[mailto:brendan@mozilla.org Brendan Eich]
|peers=
|group=
|source_dirs=tools/README
|url=
|components=
}}

{{Module
|name=Necko
|description=The Mozilla Networking Library
|owner=[mailto:mcmanus@ducksong.com Patrick McManus]
|peers= [mailto:jduell.mcbugs@gmail.com Jason Duell], [mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:mnovotny@mozilla.com Michal Novotny], [mailto:hurley@mozilla.com Nick Hurley], [mailto:dd.mozilla@gmail.com Dragana Damjanovic ],[mailto:valentin.gosu@gmail.com Valentin Gosu],[mailto:daniel@haxx.se Daniel Stenberg ]
|peersemeritus= [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:sworkman@mozilla.com Steve Workman]
|group=dev-tech-network
|source_dirs=netwerk/%, netwerk/base/, netwerk/build/, netwerk/cache/, netwerk/dns/, netwerk/locales/, netwerk/mime/, netwerk/protocol/, netwerk/resources/, netwerk/socket/, netwerk/streamconv/, netwerk/system/, netwerk/test/, netwerk/testserver/
|url=http://www.mozilla.org/projects/netlib/, https://developer.mozilla.org/en/Necko
|components=Core::Networking, Core::Networking: Cache, Core::Networking: Cookies, Core::Networking: FTP, Core::Networking: File, Core::Networking: HTTP, Core::Networking: JAR, Core::Networking: Websockets
}}

{{Module
|name=NSPR
|description=Netscape Portable Runtime
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:wtc@google.com Wan-Teh Chang], [mailto:mh@glandium.org Mike Hommey], [mailto:kaie@kuix.de Kai Engert]
|group=dev-tech-nspr
|source_dirs=nsprpub/
|url=http://www.mozilla.org/projects/nspr/
http://www.mozilla.org/projects/nspr/reference/html/
http://www.mozilla.org/projects/nspr/release-notes/
|components=NSPR
}}

{{Module
|name=PDF
|description=Rendering code to display documents encoded in the ISO 32000-1 `PDF' format.
|owner=Chris Jones, Andreas Gal
|peers=[mailto:aadib@mozilla.com Artur Adib], [mailto:bdahl@mozilla.com Brendan Dahl], [mailto:vnicolas@mozilla.com Vivien Nicolas]
|group=dev-platform
|source_dirs=media/pdf/
|url=https://github.com/mozilla/pdf.js
|components=Core::PDF
}}

{{Module
|name=Plugins
|description= NPAPI Plugin support.
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:jst@mozilla.org Johnny Stenback], [mailto:roc+@cs.cmu.edu Robert O'Callahan], [mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:joshmoz@gmail.com Josh Aas]
|peersemeritus=[mailto:john@pointysoftware.net John Schoenick]
|group=
|source_dirs=dom/plugins/, modules/plugin/
|url=https://wiki.mozilla.org/Plugins
|components=Core::Plug-ins
}}

{{Module
|name=Preferences
|description=Preference library
|owner=
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|group=dev-platform
|source_dirs=modules/libpref/
|url=
|components=Core::Preferences: Backend
}}

{{Module
|name=Private Browsing
|description=Implementation of the Private Browsing mode, and the integration of other modules with Private Browsing APIs.
|owner=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:josh@joshmatthews.net Josh Matthews]
|group=dev-platform
|source_dirs=Implementation and consumers of Private Browsing APIs in nsILoadContext, nsIPrivateBrowsingChannel, PrivateBrowsingUtils.jsm and the related glue code.
|url=https://wiki.mozilla.org/Private_Browsing
|components=Firefox::Private Browsing
}}

{{Module
|name=Privilege Manager
|description="caps"
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dveditz@mozilla.com Dan Veditz], [mailto:jst@mozilla.org Johnny Stenback]
|group=dev-tech-dom
|source_dirs=caps/
|url=http://www.mozilla.org/projects/security/components/index.html
|components=Core::Security: CAPS
}}

{{Module
|name=Push Notifications
|description=Push is a way for application developers to send messages to their web applications.
|owner=[mailto:doug.turner@gmail.com Doug Turner]
|peers=[mailto:nsm.nikhil@gmail.com Nikhil Marathe], [mailto:kcambridge@mozilla.com Kit Cambridge], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:ddamjanovic@mozilla.com Dragana Damjanovic]
|group=
|source_dirs=dom/push, dom/simplepush
|url=
|components=
}}

{{Module
|name=PyXPCOM
|description=The Python to XPCOM bridge.
|owner=Todd Whiteman
|peers=[mailto:mhammond@skippinet.com.au Mark Hammond]
|group=
|source_dirs=extension/python
|url=https://developer.mozilla.org/en/PyXPCOM
|components=
}}

{{Module
|name=Qt-based gfx and widget
|description=Qt-based rendering and widget code
|owner=[mailto:romaxa@gmail.com Oleg Romashin]
|peers=[mailto:mozilla@rosenauer.org Wolfgang Rosenauer], [mailto:doug.turner@gmail.com Doug Turner]
|group=dev-tech-widget
|source_dirs=widget/qt/
|url=
|components=Core::Widget: Qt
}}

{{Module
|name=RDF
|description=
|owner=[mailto:axel@pike.org Axel Hecht]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|group=dev-tech-rdf
|source_dirs=rdf/
|url=http://www.mozilla.org/rdf/doc/
|components=Core::RDF
}}

{{Module
|name=security
|description=Crypto/PKI code, including NSS (Network Security Services) and JSS (NSS for Java)
|owner=[mailto:rrelyea@redhat.com Bob Relyea], [mailto:wtc@google.com Wan-Teh Chang]
|peers=[mailto:emaldona@redhat.com Elio Maldonado], [mailto:kaie@kuix.de Kai Engert], [mailto:ryan.sleevi@gmail.com Ryan Sleevi], [mailto:ekr@rtfm.com Eric Rescorla], [mailto:franziskuskiefer@gmail.com Franziskus Kiefer], [mailto:martin.thomson@gmail.com Martin Thomson], [mailto:ttaubert@mozilla.com Tim Taubert]
|group=dev-tech-crypto
|source_dirs=dbm/, security/coreconf/, security/dbm/, security/jss/, security/nss/, security/tinderbox/, security/tinderlight/
|url=http://mozilla.org/projects/security/pki/
|components=NSS, JSS, Core::Security, Core::Security: S/MIME
}}

{{Module
|name=Security - Mozilla PSM Glue
|description=Personal Security Manager
|owner=[mailto:dkeeler@mozilla.com David Keeler]
|peers=[mailto:honzab.moz@firemni.cz Honza Bambas], [mailto:cykesiopka.bmo@gmail.com Cykesiopka]
|group=dev-tech-crypto
|source_dirs=security/manager/
|url=
|components=Core::Security: PSM, Core::Security: UI
}}

{{Module
|name=Static analysis & rewriting for C++
|description=Tools for checking C++ code looking for problems at compile time, plus tools for automated rewriting of C++ code.
|owner=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:sfink@mozilla.com Steve Fink], [mailto:michael@thelayzells.com Michael Layzell], [mailto:jrmuizel@mozilla.com Jeff Muizelaar], [mailto:birunthan@mohanathas.com Birunthan Mohanathas]
|group=dev-platform
|source_dirs=build/clang-plugin, tools/rewriting among other out of tree tools
|url=
|components=Core::Rewriting & Analysis
}}
{{Module
|name=storage
|description=Storage APIs with a SQLite backend
|owner=[mailto:mak77@bonardo.net Marco Bonardo]
|peers=[mailto:bugmail@asutherland.org Andrew Sutherland], [mailto:bent.mozillla@gmail.com Ben Turner]
|group=dev-platform
|source_dirs=db/sqlite3/, storage/
|url=http://developer.mozilla.org/en/docs/Storage
|components=Toolkit::Storage, Core::SQL
}}

{{Module
|name=String
|description=
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:jlebar@mozilla.com Justin Lebar]
|group=dev-tech-xpcom
|source_dirs=string/, xpcom/string/
|url=https://developer.mozilla.org/En/Mozilla_internal_string_guide
|components=Core::String
}}

{{Module
|name=Style System
|description=CSS style sheet handling; style data computation
|owner=[mailto:dbaron@dbaron.org David Baron]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:cam@mcc.id.au Cameron McCormack]
|group=dev-tech-layout
|source_dirs=layout/style/
|url=https://wiki.mozilla.org/Gecko:Overview#Style_System
|components=Core::CSS Parsing and Computation
}}

{{Module
|name=SVG
|description=Scalable Vector Graphics
|owner=[mailto:jwatt@jwatt.org Jonathan Watt]
|peers=[mailto:longsonr@gmail.com Robert Longson], [mailto:roc+@cs.cmu.edu Robert O'Callahan], [mailto:dholbert@mozilla.com Daniel Holbert], [mailto:birtles@gmail.com Brian Birtles]
|group=dev-tech-svg
|source_dirs=dom/svg/, layout/svg/, dom/smil/
|url=https://developer.mozilla.org/en-US/docs/Web/SVG
|components=Core::SVG
}}

{{Module
|name=Tamarin
|description=VM for ActionScript and JavaScript
|owner=Edwin Smith, [mailto:jodyer@adobe.com Jeff Dyer]
|peers=[mailto:brendan@mozilla.org Brendan Eich], [mailto:stejohns@adobe.com Steven Johnson], [mailto:tierney@adobe.com Erik Tierney], [mailto:treilly@adobe.com Tom Reilly]
|group=dev-tech-js-engine
|source_dirs=js/tamarin
|url=http://www.mozilla.org/projects/tamarin/
http://wiki.mozilla.org/tamarin/
http://hg.mozilla.org/tamarin-central/
http://hg.mozilla.org/tamarin-tracing/
|components=Tamarin
}}

{{Module
|name=Test Harness
|description=In-tree test infrastructure and tools. Harnesses include, XPCShell, Mochitest (& Chrome), Reftest, JsREftest, Compiled Code Tests, Robocop, Mozmill, Marionette, Firefox UI Tests. Requests for new harnesses should go to Testing::General.
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:dbaron@dbaron.org David Baron] (reftest), [mailto:jwalden@mit.edu Jeff Walden] (httpd.js, jsreftest), Rob Campbell (mochitest, mochitest chrome, marionette), [mailto:jmaher@mozilla.com Joel Maher] (reftest, mochitest, jsreftest), [mailto:ctalbert@mozilla.com Clint Talbert] (reftest, compiled code, mozmill), [mailto:geoffbrown@mozilla.com Geoff Brown] (robocop), [mailto:hskupin@mozilla.com Henrik Skupin] (Marionette, Firefox UI tests), [mailto:ato@mozilla.com Andreas Tolfsen] (marionette), [mailto:jgriffin Jonathan Griffin] (marionette), [mailto:dburns@mozilla.com David Burns] (marionette) [mailto:dminor@mozilla.com Dan Minor], [mailto:mjzffr@gmail.com Maja Frydrychowicz] (Marionette, Firefox UI tests),

|group=dev-quality
|source_dirs=/testing
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::General, Testing::Mochitest, Testing::Mochitest Chrome, Testing::Marionette, Testing::Mozmill, Testing::Reftest, Testing::XPCShell Harness, Testing::httpd.js
}}

{{Module
|name=Testing Infrastructure
|description=Testing tools and infrastructure for Mozilla projects, harnesses for automated tests, stand-alone test tools. Talos, Graph Server, Mozbase, Pulse, WOO, Bughunter, SUTAgent, Eideticker
|owner=[mailto:jmaher@mozilla.com Joel Maher]
|peers=[mailto:bclary@bclary.com Bob Clary], [mailto:bhearsum@mozilla.com Ben Hearsum], [mailto:ccooper@deadsquid.com Chris Cooper], [mailto:ctalbert@mozilla.com Clint Talbert], [mailto:robert@roberthelmer.com Robert Helmer], [mailto:jmaher@mozilla.com Joel Maher], Rob Campbell, [mailto:wlach@mozilla.com William Lachance], [mailto:jeads@mozilla.com Jonathan Eads], [mailto:jgriffin Jonathan Griffin], [mailto:bmoss@mozilla.com Bob Moss], [mailto:mcote@mozilla.com Mark Côté]
|group=dev-quality
|source_dirs=testing/, tools/httptester/, tools/page-loader/, tools/test-harness/, tools/tests/, tools/testserver/, tools/testy/
|url=http://wiki.mozilla.org/SoftwareTesting
|components=Testing::Infrastructure
}}

{{Module
|name=JS Marionette
|description=NodeJS test harness, marionette client, and other utilities for running marionette tests (submodule of Test Infrastructure)
|owner=[mailto:jlal@mozilla.com James Lal] <lightsofapollo>, [mailto:gaye@mozilla.com Gareth Aye] <gaye>
|peers=[mailto:aus@mozilla.com Ghislain "Aus" Lacroix] <auswerk>
|source_dirs=gaia/tests/jsmarionette
|components=Testing::JSMarionette
|group=dev-gaia
}}

{{Module
|name=XPCShell Test Harness
|description=The XPCShell Harness
|owner=[mailto:ted@mielczarek.org Ted Mielczarek]
|peers=[mailto:jmaher@mozilla.com Joel Maher]
|source_dirs=testing/xpcshell
|components=Testing::XPCShell Harness
}}

{{Module
|name=Update Service
|description=server code for Mozilla Update services (aus, addons, pfs)
|owner=Mike Morgan
|peers=[mailto:jscott@mozilla.com Justin Scott], [mailto:shaver@mozilla.org Mike Shaver], [mailto:wclouser@mozilla.com Will Clouser]
|group=dev-amo
|source_dirs=webtools/addons/, webtools/aus/, webtools/update/
|url=http://wiki.mozilla.org/wiki/AMO
|components=AUS::Administration, AUS::Systems
}}

{{Module
|name=View System
|description=The View Manager is responsible for handling "heavyweight" rendering (some clipping, compositing) and event handling tasks.
|owner=[mailto:roc+@cs.cmu.edu Robert O'Callahan]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:dbaron@dbaron.org David Baron]
|group=dev-tech-layout
|source_dirs=view/
|url=
|components=Core::Layout: View Rendering
}}

{{Module
|name=Web Audio
|description=Support for the W3C Web Audio API specification.
|owner=[mailto:ehsan@mozilla.com Ehsan Akhgari]
|peers=[mailto:roc+@cs.cmu.edu Robert O'Callahan], [mailto:padenot@mozilla.com Paul Adenot], [mailto:karlt+@karlt.net Karl Tomlinson]
|group=dev-platform
|source_dirs=dom/media/webaudio
|url=https://wiki.mozilla.org/Web_Audio_API
|components=Core::Web Audio
}}

{{Module
|name=WebRTC
|description=WebRTC is responsible for realtime audio and video communication, as well as related issues like low-level camera and microphone access
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:ehugg@cisco.com Ethan Hugg], [mailto:bcampen@mozilla.com Byron Campen] [mailto:abr@mozilla.com Adam Roach]
|group=dev-media
|source_dirs=N/A (see submodules "WebRTC Media" and "WebRTC Signaling")
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC
}}

{{Module
|name=Widget
|description=
|owner=[mailto:roc+@cs.cmu.edu Robert O'Callahan]
|peers=[mailto:pavlov@pavlov.net Stuart Parmenter], [mailto:vladimir@pobox.com Vladimir Vukicevic]
|group=dev-platform
|source_dirs=widget/, widget/xpwidgets/
|url=
|components=Core::Drag and Drop, Core::Widget, Core::Printing: Setup
}}

{{Module
|name=Widget - Android
|description=The Android Port
|owner=[mailto:blassey.bugs@lassey.us Brad Lassey]
|peers=[mailto:jwillcox@mozilla.com James Willcox]
|group=dev-platforms-mobile
|source_dirs=widget/android/, embedding/android
|url=
|components=Core::Widget: Android
}}

{{Module
|name=Widget - GTK
|description=supported X widgetry and gfx
|owner=[mailto:roc+@cs.cmu.edu Robert O'Callahan]
|peers=[mailto:karlt+@karlt.net Karl Tomlinson]
|group=dev-platform
|source_dirs=widget/gtk/, widget/gtk2/, widget/gtksuperwin/, widget/gtkxtbin/
|url=http://www.mozilla.org/unix/, http://www.gtk.org, http://www.mozilla.org/ports/gtk/
|components=Core::Widget: Gtk
}}

{{Module
|name=Widget - OS X
|description= Gecko's OS X compatibility layer.
|owner=[mailto:mstange@themasta.com Markus Stange]
|peers=[mailto:joshmoz@gmail.com Josh Aas], [mailto:bgirard@mozilla.com Benoit Girard], [mailto:spohl@mozilla.com Stephen Pohl], [mailto:smichaud@pobox.com Steven Michaud]
|group=dev-platform
|source_dirs=widget/cocoa/
|url=
|components=Core::Widget: Cocoa
}}

{{Module
|name=Widget - Windows
|description=Windows widgets and desktop integration
|owner=[mailto:jmathies@mozilla.com Jim Mathies]
|peers=[mailto:blassey@mozilla.com Brad Lassey], [mailto:netzen@gmail.com Brian Bondy], [mailto:cbiesinger@gmail.com Christian Biesinger], [mailto:doug.turner@gmail.com Doug Turner], [mailto:neil@parkwaycc.co.uk Neil Rashbrook], [mailto:robarnold@cmu.edu Rob Arnold], [mailto:timeless@mozdev.org Josh 'timeless' Soref], [mailto:vladimir@pobox.com Vladimir Vukicevic]
|group=dev-platform
|source_dirs=widget/windows/
|url=
|components=Core::Widget: Win32
}}

{{Module
|name=XBL
|description=eXtensible Binding Language
|owner=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jonas@sicking.cc Jonas Sicking]
|peers=[mailto:mrbkap@gmail.com Blake Kaplan], [mailto:bobbyholley@gmail.com Bobby Holley]
|group=dev-tech-xbl
|source_dirs=dom/xbl/
|url=http://www.mozilla.org/projects/xbl/
|components=Core::XBL
}}

{{Module
|name=XML
|description=XML in Mozilla, including XML, XHTML, Namespaces in XML, Associating Style Sheets with XML Documents, XML Linking and XML Extras. XML-related things that are not covered by more specific projects.
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jonas@sicking.cc Jonas Sicking], [mailto:jst@mozilla.org Johnny Stenback]
|group=dev-tech-xml
|source_dirs=dom/xml/, extensions/xmlextras/, parser/expat/
|url=http://www.mozilla.org/newlayout/xml/
|components=Core::XML
}}

{{Module
|name=XPApps
|description=Cross-Platform Applications, mostly Navigator front end and application shell.
|owner=[mailto:neil@parkwaycc.co.uk Neil Rashbrook]
|peers=[mailto:dean_tessman@hotmail.com Dean Tessman], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-apps-seamonkey
|source_dirs=xpfe/
|url=http://www.mozilla.org/xpapps/
|components=
}}

{{Module
|name=XPCOM
|description=The cross-platform object model and core data structures.
|owner=[https://mozillians.org/en-US/u/froydnj/ Nathan Froyd]
|peers=[https://mozillians.org/en-US/u/dougt/ Doug Turner], [https://mozillians.org/en-US/u/bsmedberg/ Benjamin Smedberg]
|group=dev-platform
|source_dirs=startupcache/, xpcom/%, xpcom/base/, xpcom/build/, xpcom/components/, xpcom/ds/, xpcom/glue/, xpcom/proxy/, xpcom/sample/, xpcom/stub/, xpcom/tests/, xpcom/threads/, xpcom/tools/, xpcom/windbgdlg/
|url=http://developer.mozilla.org/en/XPCOM
|components=Core::XPCOM
}}

{{Module
|name=XPConnect
|description=Deep Magic
|owner=[mailto:bobbyholley@gmail.com Bobby Holley]
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jst@mozilla.org Johnny Stenback], [mailto:peterv@propagandism.org Peter Van der Beken], [mailto:mrbkap@gmail.com Blake Kaplan], [mailto:gkrizsanits@mozilla.com Gabor Krizsanits]
|peersemeritus=[mailto:gal@uci.edu Andreas Gal]
|group=
|source_dirs=js/xpconnect/
|url=
|components=Core::XPConnect
}}

{{Module
|name=XPIDL
|description=Cross-platform IDL compiler; produces .h C++ header files and .xpt runtime type description files from .idl interface description files.
|owner=[mailto:me@kylehuey.com Kyle Huey]
|peers=[mailto:shaver@mozilla.org Mike Shaver], [mailto:timeless@mozdev.org Josh 'timeless' Soref]
|group=dev-tech-xpcom
|source_dirs=xpcom/typelib/
|url=http://www.mozilla.org/scriptable/xpidl
http://www.mozilla.org/scriptable
|components=
}}

{{Module
|name=XPInstall
|description=
|owner=[mailto:dveditz@mozilla.com Dan Veditz]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg]
|group=dev-tech-xpinstall
|source_dirs=xpinstall/
|url=
|components=Core::Installer: XPInstall Engine
}}

{{Module
|name=xptcall
|description=XPTCall - platform-specific assembly for calling and implementing arbitrary XPCOM interfaces.
|owner=[mailto:timeless@mozdev.org Josh 'timeless' Soref]
|peers=[mailto:benjamin@smedbergs.us Benjamin Smedberg], [mailto:shaver@mozilla.org Mike Shaver]
|group=dev-xpcom
|source_dirs=xpcom/reflect/xptcall/
|url=http://www.mozilla.org/scriptable/xptcall-faq.html
|components=
}}

{{Module
|name=XPToolkit
|description=Cross-platform user interface toolkit
|owner=
|peers=[mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:Jan.Varga@gmail.com Jan Varga]
|group=dev-tech-xul
|source_dirs=dom/xul/, layout/xul/
|url=http://www.mozilla.org/xpfe/
|components=Core::XP Toolkit/Widgets: Menus, Core::XP Toolkit/Widgets: XUL
}}

{{Module
|name=XSLT Processor
|description=XSLT transformations processor
|owner=[mailto:peterv@propagandism.org Peter Van der Beken]
|peers=[mailto:axel@pike.org Axel Hecht], [mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xslt
|source_dirs=dom/xslt/
|url=http://www.mozilla.org/projects/xslt/, http://www.w3.org/TR/xslt.html
|components=Core::XSLT
}}

{{Module
|name=XTF
|description=eXtensible Tag Framework
|owner=
|peers=[mailto:alex@croczilla.com alex@croczilla.com], [mailto:bzbarsky@mit.edu Boris Zbarsky], [mailto:jonas@sicking.cc Jonas Sicking]
|group=dev-tech-xbl
|source_dirs=content/xtf/, layout/xtf/
|url=http://www.croczilla.com/bits_and_pieces/xtf/
|components=Core::XTF
}}

{{Module
|name=Sandboxing
|description=Cross platform sandboxing
|owner=[mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|peers=[mailto:bowen@mozilla.com Bob Owen], [mailto:aklotz@mozilla.com Aaron Klotz], [https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes], [mailto:gDestuynder@mozilla.com Guillaume Destuynder], [mailto:bsmedberg@mozilla.com Benjamin Smedberg], [mailto:jld@mozilla.com Jed Davis]
|group=dev-platform
|source_dirs=security/sandbox
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Windows
|description=Sandboxing for the Windows platform
|owner=[mailto:bowen@mozilla.com Bob Owen]
|peers=[mailto:netzen@gmail.com Brian Bondy], [mailto:aklotz@mozilla.com Aaron Klotz], [https://mozillians.org/en-US/u/TimAbraldes Tim Abraldes], [mailto:jimm@mozilla.com Jim Mathies]
|group=dev-platform
|source_dirs=security/sandbox/win
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - OSX
|description=Sandboxing for the OSX platform
|owner=[mailto:haftandilian@mozilla.com Haik Aftandilian]
|peers=
|group=dev-platform
|source_dirs=security/sandbox/mac
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

{{Module
|name=Sandboxing - Linux & B2G
|description=Sandboxing for the Linux & B2G platforms
|owner=[mailto:jhector@mozilla.com Julian Hector]
|peers=[mailto:jld@mozilla.com Jed Davis] [mailto:gcp@mozilla.com Gian-Carlo Pascutto]
|group=dev-platform
|source_dirs=security/sandbox/linux
|url=https://wiki.mozilla.org/Security/Sandbox
|components=Core::Security: Process Sandboxing
}}

===Submodules===
{{Module
|name=Build Config - Fennec
|description=Submodule of the build config covering Fennec's build system in mobile/android.
|owner=[mailto:gps@mozilla.com Gregory Szorc]
|peers=Same as Build Config plus [mailto:nalexander@mozilla.com Nicholas Alexander].
|group=dev-builds
|components=Core::Build Config
}}

{{Module
|name=WebRTC Media
|description=Submodule of WebRTC responsible for access to media input devices (microphones, cameras, screen capture), as well as realtime audiovisual codecs and packetization.
|owner=[mailto:rjesup@mozilla.com Randell Jesup]
|peers=[mailto:ehugg@cisco.com Ethan Hugg], [mailto:pkerr@mozilla.com Paul Kerr]
|group=dev-media
|source_dirs=/media/webrtc, /dom/media/webrtc
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Audio/Video)
}}

{{Module
|name=WebRTC Signaling
|description=Submodule of WebRTC responsible for implementation of PeerConnection API, WebRTC identity, and SDP/JSEP handling
|owner=[mailto:bcampen@mozilla.com Byron Campen]
|peers=[mailto:ekr@mozilla.com Eric Rescorla], [mailto:abr@mozilla.com Adam Roach], [mailto:rjesup@mozilla.com Randell Jesup], [mailto:nohlmeier@mozilla.com Nils Ohlmeier]
|group=dev-media
|source_dirs=/media/peerconnection, /dom/media/peerconnection ''(note: file reorg underway)''
|url=https://wiki.mozilla.org/Media/webrtc
|components=Core::WebRTC (Signaling)
}}

<noinclude>

===Unassigned Bugzilla Components===

The following Bugzilla components in the Core project have not been assigned to a module (this list is not exhaustive):

<pre>
Core::File Handling
Core::Find Backend
Core::Gecko Profiler
Core::General
Core::HTML: Form Submission
Core::History: Global
Core::Image Blocking
Core::JavaScript Debugging APIs
Core::Localization
Core::Nanojit
Core::Networking: Domain Lists
Core::Print Preview
Core::Printing: Output
Core::Printing: Setup
Core::Profile: BackEnd
Core::Profile: Migration
Core::Profile: Roaming
Core::QuickLaunch (AKA turbo mode)
Core::Rewriting and Analysis
Core::Selection
Core::Serializers
Core::Spelling checker
Core::Tracking
Core::Web Services
Core::WebDAV
Core::Widget: OS/2
Core::Widget: Photon
Core::X-remote
Core::XForms
Core::XUL
</pre>
</noinclude>

Accessibility/WebAccessibilityAPI

2015-05-08T15:06:18Z

Surkov.alexander: /* Questions/concerns */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

====Questions/concerns====

* Interactions should be extended to allow to specify a control that triggers the action. The concept is described by InidieUI: you can use mouse, touchscreen, keyboard, voice control or a control element to invoke the action. Maybe Interactions should be renamed to Triggers to share terms with IndieUI.

Here's the image of InideUI action/interaction concept.
<div style="height: 254px; overflow: hidden;">
http://www.w3.org/WAI/intro/iui-scroll.png
</div>

Alternatively we could introduce relations between actions like "triggers" and "triggeredby".

* What about highlevel actions (uberactions), for example, "press" buttons means "send something somewhere". This may be covered by label. Another example, selected listitem on the left changes a view on the right, "select" actions has meaning of "change view". Or checkbox that enables/disables related controls, "check/uncheck" action means "enable/disable controls". These examples correlates to controlledby/controllerfor relations, but the relations doesn't reveal type of control.

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text(AccessiblePos)''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text(CriteriaLiteral)''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The idea is to help the author to keep the code less verbose as possible. If role implies a number of preset attributes or states then they are present on the accessible element by default, i.e. if the author didn't list them. For example, if <code>listitem</code> role is selectable and focusable by default then the author doesn't have to point <code>selectable</code> and <code>focusable</code> states when he describes a listitem source, in other words, these code snippets are equivalent:

<pre>
var source1 = {
role: "listitem"
};

var source2 = {
role: "listitem",
states: [ "selectable", "focusable" ]
};
</pre>

Implied semantics is described by [[#SemanticsProviders|taxonomies]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API, I tend to think that the author should be able to replace/remove native semantics if needed. This can ruin the web page but it gives the absolute control over the page content. A dangerous but quite powerful tool like atomic energy. ]

===Sniffing===

In order to make an optimization, the content provider has to know whether an accessibility consumer (like screen reader) is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-08T14:54:33Z

Surkov.alexander: /* Interactions */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

====Questions/concerns====

* Interactions should be extended to allow to specify a control that triggers the action. The concept is described by InidieUI: you can use mouse, touchscreen, keyboard, voice control or a control element to invoke the action. Maybe Interactions should be renamed to Triggers to share terms with IndieUI.

Here's the image of InideUI action/interaction concept.
http://www.w3.org/WAI/intro/iui-scroll.png

Alternatively we could introduce relations between actions like "triggers" and "triggeredby".

* What about highlevel actions (uberactions), for example, "press" buttons means "send something somewhere". This may be covered by label. Another example, selected listitem on the left changes a view on the right, "select" actions has meaning of "change view". Or checkbox that enables/disables related controls, "check/uncheck" action means "enable/disable controls". These examples correlates to controlledby/controllerfor relations, but the relations doesn't reveal type of control.

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text(AccessiblePos)''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text(CriteriaLiteral)''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The idea is to help the author to keep the code less verbose as possible. If role implies a number of preset attributes or states then they are present on the accessible element by default, i.e. if the author didn't list them. For example, if <code>listitem</code> role is selectable and focusable by default then the author doesn't have to point <code>selectable</code> and <code>focusable</code> states when he describes a listitem source, in other words, these code snippets are equivalent:

<pre>
var source1 = {
role: "listitem"
};

var source2 = {
role: "listitem",
states: [ "selectable", "focusable" ]
};
</pre>

Implied semantics is described by [[#SemanticsProviders|taxonomies]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API, I tend to think that the author should be able to replace/remove native semantics if needed. This can ruin the web page but it gives the absolute control over the page content. A dangerous but quite powerful tool like atomic energy. ]

===Sniffing===

In order to make an optimization, the content provider has to know whether an accessibility consumer (like screen reader) is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-08T13:08:14Z

Surkov.alexander: /* Interactions */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

Questions/concerns
* Interactions should be extended to allow to specify a control that triggers the action. The concept is described by InidieUI: you can use mouse, touchscreen, keyboard, voice control or a control element to invoke the action. Maybe Interactions should be renamed to Triggers to share terms with IndieUI.

Here's the image of InideUI action/interaction concept.
http://www.w3.org/WAI/intro/iui-scroll.png

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text(AccessiblePos)''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text(CriteriaLiteral)''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The idea is to help the author to keep the code less verbose as possible. If role implies a number of preset attributes or states then they are present on the accessible element by default, i.e. if the author didn't list them. For example, if <code>listitem</code> role is selectable and focusable by default then the author doesn't have to point <code>selectable</code> and <code>focusable</code> states when he describes a listitem source, in other words, these code snippets are equivalent:

<pre>
var source1 = {
role: "listitem"
};

var source2 = {
role: "listitem",
states: [ "selectable", "focusable" ]
};
</pre>

Implied semantics is described by [[#SemanticsProviders|taxonomies]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API, I tend to think that the author should be able to replace/remove native semantics if needed. This can ruin the web page but it gives the absolute control over the page content. A dangerous but quite powerful tool like atomic energy. ]

===Sniffing===

In order to make an optimization, the content provider has to know whether an accessibility consumer (like screen reader) is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-08T12:46:16Z

Surkov.alexander: /* Sniffing */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text(AccessiblePos)''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text(CriteriaLiteral)''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The idea is to help the author to keep the code less verbose as possible. If role implies a number of preset attributes or states then they are present on the accessible element by default, i.e. if the author didn't list them. For example, if <code>listitem</code> role is selectable and focusable by default then the author doesn't have to point <code>selectable</code> and <code>focusable</code> states when he describes a listitem source, in other words, these code snippets are equivalent:

<pre>
var source1 = {
role: "listitem"
};

var source2 = {
role: "listitem",
states: [ "selectable", "focusable" ]
};
</pre>

Implied semantics is described by [[#SemanticsProviders|taxonomies]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API, I tend to think that the author should be able to replace/remove native semantics if needed. This can ruin the web page but it gives the absolute control over the page content. A dangerous but quite powerful tool like atomic energy. ]

===Sniffing===

In order to make an optimization, the content provider has to know whether an accessibility consumer (like screen reader) is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-08T12:44:51Z

Surkov.alexander: /* Conflicts */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text(AccessiblePos)''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text(CriteriaLiteral)''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The idea is to help the author to keep the code less verbose as possible. If role implies a number of preset attributes or states then they are present on the accessible element by default, i.e. if the author didn't list them. For example, if <code>listitem</code> role is selectable and focusable by default then the author doesn't have to point <code>selectable</code> and <code>focusable</code> states when he describes a listitem source, in other words, these code snippets are equivalent:

<pre>
var source1 = {
role: "listitem"
};

var source2 = {
role: "listitem",
states: [ "selectable", "focusable" ]
};
</pre>

Implied semantics is described by [[#SemanticsProviders|taxonomies]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API, I tend to think that the author should be able to replace/remove native semantics if needed. This can ruin the web page but it gives the absolute control over the page content. A dangerous but quite powerful tool like atomic energy. ]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-08T12:44:31Z

Surkov.alexander: /* Conflicts */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text(AccessiblePos)''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text(CriteriaLiteral)''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The idea is to help the author to keep the code less verbose as possible. If role implies a number of preset attributes or states then they are present on the accessible element by default, i.e. if the author didn't list them. For example, if <code>listitem</code> role is selectable and focusable by default then the author doesn't have to point <code>selectable</code> and <code>focusable</code> states when he describes a listitem source, in other words, these code snippets are equivalent:

<pre>
var source1 = {
role: "listitem"
};

var source2 = {
role: "listitem",
states: [ "selectable", "focusable" ]
};
</pre>

Implied semantics is described by [[#SemanticsProviders|taxonomies]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API, I tend to think that the author should be able to replace/remove native semantics if needed. This can ruin the web page but it gives the absolute control over the page content. A dangerous but quite powerful tool like atomic energy. ]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-08T12:40:03Z

Surkov.alexander: /* Implied semantics */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text(AccessiblePos)''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text(CriteriaLiteral)''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The idea is to help the author to keep the code less verbose as possible. If role implies a number of preset attributes or states then they are present on the accessible element by default, i.e. if the author didn't list them. For example, if <code>listitem</code> role is selectable and focusable by default then the author doesn't have to point <code>selectable</code> and <code>focusable</code> states when he describes a listitem source, in other words, these code snippets are equivalent:

<pre>
var source1 = {
role: "listitem"
};

var source2 = {
role: "listitem",
states: [ "selectable", "focusable" ]
};
</pre>

Implied semantics is described by [[#SemanticsProviders|taxonomies]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T19:49:11Z

Surkov.alexander: /* Text */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text(AccessiblePos)''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text(CriteriaLiteral)''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T19:37:22Z

Surkov.alexander: /* States */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },

singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},

readonly: { },
editable: { },
required: { },

checked: {
exlusives: [ "mixed" ]
},
mixed: {
exlusives: [ "checked" ]
}
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T19:35:47Z

Surkov.alexander: /* States */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString exclusives;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''exclusives''
::Mutually exclusive states if applicable. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
exlcusives: [ "multiline" ]
},
multiline: {
exlcusives: [ "singleline" ]
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T18:12:47Z

Surkov.alexander: /* Roles */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> relations;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon .''relations''
::List of relations supported by the role.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString opposite;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''opposite''
::An opposite state if any. Opposite state are mutually exclusive. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
opposite: "multiline"
},
multiline: {
opposite: "singleline"
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T18:10:00Z

Surkov.alexander: /* Music sheet example */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString opposite;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''opposite''
::An opposite state if any. Opposite state are mutually exclusive. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
opposite: "multiline"
},
multiline: {
opposite: "singleline"
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Or in terms of taxonomies:

<pre>
document.import("role", {
sheet: {
description: "sheet",
attributes: [ "instrument", "tempo", "clef" ]
},
note: {
description: "note",
attributes: [ "key", "alteration", "octave", "duration", "effects" ],
relations: [ "crescendo", "diminuendo" ]
}
});

document.import("attributes", {
instrument: {
description: "instrument type"
},
tempo: {
description: "tempo"
},
clef: {
description: "clef"
},
key: {
description: "key",
values: [ "C", "D", "E", "F", "G", "A", "H" ],
},
alteration: {
description: "alteration",
values: [ "none", "flat", "sharp" ],
default: "none"
},
octave: {
description: "octave",
values: [ "contra", "great", "small", "1line", "2line" ],
},
duration: {
description: "duration"
},
effects: {
description: "effects"
}
});

document.import("relations", {
crescendo: {
description: "crescendo"
},
diminuendo: {
description: "diminuendo"
}
});
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T17:44:19Z

Surkov.alexander:

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">
===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString opposite;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''opposite''
::An opposite state if any. Opposite state are mutually exclusive. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
opposite: "multiline"
},
multiline: {
opposite: "singleline"
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T17:43:48Z

Surkov.alexander: /* Actions */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

<div id="AccessibleSource">

===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString opposite;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''opposite''
::An opposite state if any. Opposite state are mutually exclusive. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
opposite: "multiline"
},
multiline: {
opposite: "singleline"
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T17:42:13Z

Surkov.alexander: /* Roles */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

====Actions====

<pre>
partial interface ActionMap {
void tweak(DOMString oldname, DOMString newname);

void add(DOMString name, object);
void delete(DOMString name);
};
</pre>

<code>
ActionMap ..''tweak''
::Toggles the action name.
</code>

<div id="AccessibleSource">

===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
sequence<DOMString> actions;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.

RoleTaxon ..''actions''
::List of supported actions. Actions from the list are exposed on the accessible element depending on states present on it. For example, if supported actions are "check" and "uncheck", then "check" is exposed if the accessible element doesn't have "checked" state, otherwise "unchecked".
</code>

<b>Example. ARIA <code>textbox</code> role.</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>checkbox</code> role.</b>

<pre>
var taxa = {
checkbox: {
description: "checkbox",
parents: [ "input" ],
states: [ "checkable:default, "checked" ],
actions: [ "check", "uncheck" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString opposite;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''opposite''
::An opposite state if any. Opposite state are mutually exclusive. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
opposite: "multiline"
},
multiline: {
opposite: "singleline"
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T17:30:34Z

Surkov.alexander: /* Attributes */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

====Actions====

<pre>
partial interface ActionMap {
void tweak(DOMString oldname, DOMString newname);

void add(DOMString name, object);
void delete(DOMString name);
};
</pre>

<code>
ActionMap ..''tweak''
::Toggles the action name.
</code>

<div id="AccessibleSource">

===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.
</code>

<b>Example. ARIA <code>textbox</code> role</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString opposite;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''opposite''
::An opposite state if any. Opposite state are mutually exclusive. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
opposite: "multiline"
},
multiline: {
opposite: "singleline"
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

====Actions====

<pre>
dictionary ActionTaxon {
DOMString description;
DOMString dual;
sequence<DOMString> states;
};
</pre>

<code>
ActionTaxon .''description''
::Localized action description.

ActionTaxon .''dual''
::Dual action taxon. When action is invoked, it is switched to its dual action if applicable.

ActionTaxon .''states''
::Implied states. When action is invoked, states of dual action are cleared, this action states are set.
</code>

<b>Example.</b>

<pre>
var taxa = {
check: {
description: "check",
dual: "uncheck",
states: [ "checked" ]
},
uncheck: {
description: "uncheck",
dual: "check"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T17:19:44Z

Surkov.alexander:

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionMap|ActionMap]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

====ActionMap====

Accessible actions are presented by <code>ActionMap</code> map like object of pairs { action name, action object }.

<pre>
interface ActionMap {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

====Actions====

<pre>
partial interface ActionMap {
void tweak(DOMString oldname, DOMString newname);

void add(DOMString name, object);
void delete(DOMString name);
};
</pre>

<code>
ActionMap ..''tweak''
::Toggles the action name.
</code>

<div id="AccessibleSource">

===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.
</code>

<b>Example. ARIA <code>textbox</code> role</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString opposite;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''opposite''
::An opposite state if any. Opposite state are mutually exclusive. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
opposite: "multiline"
},
multiline: {
opposite: "singleline"
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>

Accessibility/WebAccessibilityAPI

2015-05-07T17:18:10Z

Surkov.alexander: /* Relations */

=Introduction=

There's number of objectives on the web to improve accessibility and usability support. Web applications want to provide special support for their users, helping them navigate and perceive the content. The browser has a number of add-ons serving to improve accessibility support, for example, the app letting to navigate landmarks on the web page. These tasks require accessibility API similar to what desktop assistive technologies have.

Web accessibility API also allows for in-browser automated accessibility testing of web content, i.e. helpful for checking that HTML and other standards in the browser are accessible to all users.

On the other hand there's a growing need for making graphical content accessible. These are charts, graphs and other various visual forms that are drawn using HTML canvas or SVG. There's also a tendency to use HTML canvas element in place of DOM because of performance matter, here's an [http://engineering.flipboard.com/2015/02/mobile-web/ example]. All markup in the example is defined in JavaScript and there is a need for a non-DOM accessibility solution to make the content accessible.

=Web accessibility API=

The API provides bunch of interfaces that are used to express the web content the way the assistive technologies (AT) knows how to deal with. In other words each piece of semantically meaningful content has associated accessible element the AT operates at. The interfaces allow to receive accessible element properties, traverse the hierarchy and interact with content.

Also the API provides a way to extend existing semantics of the markup and add new semantics for inaccessible content like canvas drawings.

==Accessible element==

This is a basic interface providing an access to the accessible element.

<pre>
interface AccessibleElement {
attribute DOMString role;

attribute DOMString name;
attribute DOMString description;
attribute DOMString value;

readonly attribute StateSet states;

readonly attribute AttributeMap attributes;

readonly attribute sequence<DOMString> patterns;
readonly attribute Object toPattern(DOMString type);

readonly attribute RelationMap relations;
AccessibleElement? relativeOf(DOMString type);

readonly attribute ActionMap actions;
void activate(DOMString action);
readonly attribute InteractionMap intreactions;

readonly attribute AccesibleElement? parent;
readonly attribute AccesibleElement? firstChild;
readonly attribute AccesibleElement? lastChild;
readonly attribute AccesibleElement? nextSibling;
readonly attribute AccesibleElement? previousSibling;
readonly attribute AccessibleChildren children;

readony attribute Node? DOMNode;
attribute AccessibleSource? source;
};
</pre>

===Node interface extension===
Accessible element can be requested from a DOM node if the DOM node is accessible, i.e. it expresses meaningful semantics to the assistive technology.
<pre>
partial interface Node {
AccessibleElement? accessibleElement;

A11eElement? a11ement; // nicer and shorter verison? // another version: accElement, accEl
};
</pre>

===Role===

<code>
AccessibleElement .''role''
::Returns accessible role as a string. Examples: "button", "menu", "textfield".
</code>

===Text properties===

<code>
AccessibleElement .''name''
::Returns accessible name.
</code>

<code>
AccessibleElement .''description''
::Returns accessible description.
</code>

<code>
AccessibleElement .''value''
::Returns accessible value if applicable.
</code>

<div id="States">
===States===
</div>

<code>
AccessibleElement .''states''
::Returns a [[#States|StateSet]] live object for all accessible states of an accessible element.
</code>

Accessible states of an accessible element are presented by the <code>StateSet</code> object. It is a live object, i.e. if the states of the accessible element change then the object reflects that. Implementation is not required to compute any state until requested.

<pre>
interface StateSet {
readonly setlike<DOMString>;

boolean hasAnyOf(DOMString ... states);
boolean hasAllOf(DOMString ... states);
};
</pre>

<code>
StateSet .''hasAnyOf''
::Returns true if any of the given states are present on the accessible element.
</code>

<code>
StateSet .''hasAllOf''
::Returns true if all given states are present on the accessible element.
</code>

Example of a script that logs to console all accessible element states.
<pre>
var accEl = document.getElementById("foo").accessibleElement;
for (let state of accElm.states) {
console.log(state);
}
</pre>

===Attributes===

The accessible element may support a number of attributes to express the semantics that cannot be described by base properties of an accessible element.

<code>
AccessibleElement .''attributes''
::Returns a [[#AttributeMap|AttributeMap]] live object for all object attributes exposed on the accessible element. If accessible element attributes are changed then the object reflects the actual state of attributes. The implementation is not required to pre-compute any of the attributes.
</code>

<div id="AttributeMap">
====AttributeMap====
</div>

<code>AttributeMap</code> is an interface aimed to work with {name, value} pairs of accessible attributes.

<pre>
interface AttributeMap {
readonly maplike<DOMString, any>;

boolean hasAnyOf(Object map); // Needs more work
boolean hasAllOf(Object map); // Needs more work
};
</pre>

<code>
AttributeSet .''hasAnyOf''
::Return true if any of the object properties matches to the object attributes.

AttributeSet .''hasAllOf''
::Return true if all of the object properties matches to the object attributes.
</code>

Each property of the object is a string or an array of strings. If array of strings is given then the object attribute is expected to have any of given values, empty array means the attribute value doesn't matter for match. String value and null values are treated as single element array or empty array correspondingly.

<b>Example #1.</b>

<pre>
var attrs = {
live: [ "assertive", "polite" ],
relevant: "show",
busy: null
};

var matched = accEl.hasAllOf(attrs);
// Matches if the ccessible element has "live" object attribute of
// "assertive" or "polite" values, has "relevant" object attribute of
// "show" value, and it has "busy" attribute.
</pre>

<b>Example #2. Process autocomplete.</b>

<pre>
var accEl = document.getElementById("foo").a11ement;

var checkObj = { autocomplete: [ "list", "both" ] };
if (accEl.attributes.hasAllOf(checkObj)) {
doAutocomplete();
}

// Alternatively you can do
var autocomplete = accEl.attributes.get("autocomplete");
if (["list", "both"].indexOf(autocomplete) != -1) {
doAutocomplete();
}
</pre>

====Attribute list====

Set of exposed attributes depends on semantics of the element. As an example, typical attributes are:

<code>
DOMString ''autocomplete'';
::Exposed on text fields. Values are ''list'', ''none'', ''inline'', ''both''.

DOMString ''live'';
::Points that the accessible is live region. Values are ''assertive'' and ''polite''.

DOMString ''relevant'';
::Lists all notifications that qualifies for live region.
</code>

===Patterns===

A pattern is a collection of attributes or methods that expresses an accessible element semantics and compliments what the AccessibleElement interface provides. The patterns concept is quite similar to attributes but tends to be more powerful. Basically, it is an alternative implementation of COM's queryInterface.

<code>
AccessibleElement .''patterns''
::Returns a list of all patterns supported by the accessible element.

Object .''toPattern''(DOMString type)
::Returns an object for the pattern of given type if supported by an accessible element.
</code>

See [[#Patters|patterns section]] for details.

===Relations===

<code>
AccessibleElement? .''relativeOf''(DOMString type)
::Returns related accessible element of the given relation type. If relation points to multiple accessible elements, the first one is returned.

RelationMap .''relations''
::Returns a map of relation types as keys and related accessible elements as values.
</code>

<pre>
interface RelationMap {
maplike<DOMString, sequence<AccessibleElement>>;
};
</pre>

====Relation types====

This is a typical list of relation types that may be exposed by an accessible element. Note, the accessible element may support custom relations as well.

<code>
''labelfor''
::Referred accessible element is an element that is labelled by this accessible element.
''labelledby''
::Referred accessible element is a label for this accessible element.
</code>

<code>
''descriptionfor''
::Referred accessible element is an element that is described by this accessible element.
''describedby''
::Referred accessible element is a description for this accessible element.
</code>

<code>
''widget''
::Return a widget the item belongs to.

''parent''
::Return a logical parent of the item. This relation may be useful for ARIA structures if the browser doesn't convert DOM flat structure into accessible hierarchical tree.
</code>

====Examples====

Console logging of all headers of the grid cell and name of the grid itself.

<pre>
var headers = cell.relations.get("labelledby");
for (let header of headers) {
console.log(header.role, header.name);
}

var grid = cell.relativeOf("widget");
console.log(grid.name);
</pre>

===Actions===

An accessible element may support actions that can be invoked on it. For example, <code>jump</code> on a link or <code>press</code> on a button, or it can be generic purpose actions like <code>scroll</code> or <code>focus</code>. Certain accessible actions may take optional parameters.

<code>
AccessibleElement .''actions''
::Returns a [[#ActionSet|ActionSet]] object of actions exposed by the accessible element. The returned object is not live, i.e. it is not updated if the accessible element actions change.
</code>

<code>
AccessibleElement .''activate''(in DOMString name, in optional any param)
::Invokes the accessible action.
::Parameters:
:::''name''
::::action name to invoke
:::''param''
::::used to provide extra context for the action
</code>

Performs the given accessible action on the accessible element.

====Action list====

<code>
''activate''
::Exposed on accessible elements that may be activated. Accessible elements may use other names for this action to emphasize the semantics they expose. For example, ''jump'' on links, ''press'' on buttons, ''check'' and ''uncheck'' on checkboxes. Accessible element may provide more than one action. For example, tree item can provide ''select''/''unselect'' as its primary action and ''expand''/''collapse'' as secondary. Tree column may implement ''sort'' action.
</code>

<code>
''focus''
::Focus on an accessible element. May be different from "activate" action, for example, in case of buttons where "activate" means press.
</code>

<code>
''scroll''
::Scrolls an accessible element into view, optionally takes coordinates relative the element to scroll the view to
::Parameter:
:::''delta'' of ''ScrollDelta''
</code>

<code>
''drag'' and ''drop''
::Used to start dragging and dropping the content related to the accessible element the action is invoked on.
</code>

<code>
''zoomin'' / ''zoomout''
::Zooms in/out the content corresponding the accessible the action is invoked on.
::Parameter:
:::''ratio'' of double, optional
</code>

<code>
''undo'' / ''redo''
::Performs clipboard operations on the accessible element of the editable content.
</code>

=====ScrollDelta param=====

<pre>
directory ScrollDelta {
int x;
int y;
int z;
DOMString mode;
};
</pre>

<code>ScrollDelta</code> structure describes a scroll change within the accessible element, the scroll change can be expressed in different units, for example, it can be in pixels or in pages. The accessible element may provide its custom set of supported modes which has to be described in [[#Taxonomy|taxonomy]].

<code>
ScrollDelta .''x'', .''y'', .''z''
::3d coordinates in the units provided by ''mode'', ''y'' and ''z'' might be optional depending on the unit.
</code>

<code>
ScrollDelta .''mode''
::A unit the coordinates are measured in. Can be on of the following values:
:::''pixel'' - ''x'', ''y'' and ''z'' (optional) specifies how many pixles to scroll (2d or 3d)
:::''line'' - ''x'' specifies how many lines to scroll
:::''paragraph'' - ''x'' specifies how many paragraphs to scroll
:::''page'' - ''x'' specifies how many pages to scroll
</code>

<div id="ActionSet">

====ActionSet====
</div>

Accessible actions are presented by <code>ActionSet</code> map like object of pairs { action name, action object }.

<pre>
interface ActionSet {
readonly maplike<DOMString, Action>;
};
</pre>

Each action is presented by <code>Action</code> interface.

<pre>
interface Action {
stingifier readonly attribute name;
readonly attribute description;
readonly InteractionSet interactions(optional DOMString device);
};
</pre>

<code>
Action .''name''
::Action name

Action .''description''
::Localized action description

Action .''interactions''
::Set of interactions (like keyboard shortcuts or mouse gestures) to invoke the action.
:::Parameters
::::device (optional)
:::::device name like 'keyboard' or 'touchscreen' the interactions should be returned for.
</code>

Here's an example of script announcing available actions on the accessible element.
<pre>
var set = accElm.actions;
if (set.size() == 0) {
say("no actions on accessible element");
} else {
say("accessible element has " + set.size() + " actions");
set.forEach(action => say(action.description));
}
</pre>

====Interactions====

A widget may support actions that can be invoked through variety of devices or by AT like screen readers. The way the action is triggered by the user is described by the interaction. Examples of user interactions are <code>swipe</code>, a mouse gesture to toggle a switch control; <code>space</code>, a key to toggle a checkbox. Access keys (<code>alt+letter</code>) and keyboard shortcuts (<code>ctrl+shift+letter</code>) used to activate the widgets are also examples of interactions. Complex widgets like grid control may support several actions, for example <code>ctrl+A</code> for <code>selectall</code> action, <code>ArrowDown/ArrowUp</code> keys for <code>movedown/moveup</code> actions, <code>ArrowRight/ArrowLeft</code> keys for <code>movenext/moveprev</code> actions.

The AT may need to know the used shortcuts to avoid possible conflicts or to supply a native way to invoke the action. For example, if presentation supports <code>swipe</code> gesture to navigate the slides then the AT can announce this info for the user.

<code>
AccessibleElement .''interactions''
::Return an ''InteractionSet'' object describing all interactions that can be performed with the accessible element.
</code>

<pre>
interface InteractionSet {
readonly maplike<DOMString, Interaction>;

boolean hasAnyOf(sequence<DOMString> interactions);
readonly attribute InteractionSet allOf(DOMString action, optional DOMString device);
};
</pre>

<code>
AccessibleElement .''hasAnyOf''
::Return true if any of given interaction are in use by the widget.
::Parameters:
:::''interaction''
::::list of interactions

AccessibleElement .''allOf''
::Return a list of all interactions with the accessible element as ''InteractionSet'' used to invoke the given action on the given device.
::Parameters:
:::''action''
::::action name
:::''device''
::::a device name, examples of supported values are "keyboard", "mouse", "touchpad".
</code>

<pre>
interface Interaction {
stingifier readonly attribute description;
readonly attribute device;
};
</pre>

Here's an example of the screen reader announcing all interactions of <code>swipe</code> action.

<pre>
var actions = accElm.actions;
actions.forEach(action => { var set = action.interactions;
say(action.name);
set.values().forEach(item => say(item.description));
});
</pre>

===Parent-child relations===

The interface provides a bunch of methods to provide access to parent/child relations between accessible elements.

<code>
AccessibleElement .''parent''
::Returns the parent accessible element if any.
</code>

<code>
AccessibleElement .''firstChild''
::Returns the first child accessible element if any.
</code>

<code>
AccessibleElement .''lastChild''
::Returns the last child accessible element if any.
</code>

<code>
AccessibleElement .''nextSibling''
::Returns the next sibling accessible element if any.
</code>

<code>
AccessibleElement .''previousSibling''
::Returns the previous sibling accessible element if any.
</code>

<code>
AccessibleElement .''children''
::Return ''AccessibleChildren'' collection of all child accessible elements.
</code>

<pre>
interface AccessibleChildren {
iterable<AccessibleElement>;
};
</pre>

Questions/concerns:
* Consider to move "widget" relation to "widget" IDL attribute (property) under this section.

===Accessible providers===

The accessible element can be created with different kinds of sources. Most of the accessible elements are created for a DOM element to expose its semantics to the assistive technology. In some cases the browser may not have underlying DOM node for the content. In this case the accessible object is created, without having a corresponding DOM element. In some cases a web author may need to change the semantics for existing elements, add new semantics or create a new accessible subtree to make content accessible. In this case the author needs to describe desired semantics in JavaScript. See [[#JSSource|Making the content accessible in JavaScript]] for details.

[[File:WebAccessibilityAPI_SourceProviders.png|The accessible element may be sourced by different kinds of providers]]

<code>
AccessibleElement .''DOMNode''
::Returns a DOM node associated with the accessible element if any. Accessible element does not have a DOM node when it is either not based on it, or when it has been detached from the DOM node. The first case happens for browser-specific implementations or for trees created in JavaScript. The second case happens when the JavaScript holds reference to the object longer than the object life cycle.
</code>

<code>
AccessibleElement .''source''
::Returns [[#AccessibleSource|AccessibleSource]] if present, refers to an accessible source, used to override accessible properties of the element.
</code>

==Content traversal==

This section describes how to traverse accessible content, for example, if you need to navigate a document by headings or navigate a paragraph by words.

A key concept of the content traversal is accessible position which describes a "location" in the document content. A position can be placed on an accessible element, for example, on a button. It can be placed before or after an accessible element, or inside of the accessible element text, for example, at the end of the first line of a paragraph.

The position can be moved forward or backward inside the document to the content complying with the given criteria. For example, criteria can be described verbally like "move the position forward to next heading" or "move the position one word back".

===Accessible Position===

<pre>
[Constructor(AccessibleElement anchor, optional Offset offset, optional AccessibleElement root),
Constructor(DOMNode container, long offset, optional AccessibleElement root),
Constructor(DOMPoint point, optional AccessibleElement root),
Constructor(AccessiblePos pos, optional AccessibleElement root)]
interface AccessiblePos {
AccessiblePos? move(AccessibleElement anchor, Offset offset);
AccessiblePos? move(DOMNode container, long offset);
AccessiblePos? move(DOMPoint);

AccessiblePos? move(Where where, Criteria);
AccessiblePos? search(Where where, Criteria);

readonly attribute AccessibleElement root;
readonly attribute AccessibleElement? anchor;
readonly attribute Offset offset;
DOMRangeBound toDOM();
};

typedef AccessiblePos A11ePos; // Short and nice name? // Maybe accPos
</pre>

====Construction====

Construction by accessible element and offset relative it.

<code>
AccessiblePos .''Constructor''(AccessibleElement, Offset, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''elm'' of ''AccessibleElement''
::::anchor accessible element of the position
:::''offset'' of ''Offset'', optional
::::an offset relative to the anchor element. If not provided then ''at'' or ''afterbegin'' is used depending on element type.
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

The offset may be either a number, a numeric mapping of caret position in the content, or a literal.

<pre>
typedef long or OffsetLiterals Offset;
enum OffsetLiterals {
"before",
"begin",
"at",
"end",
"after"
};
</pre>

<code>
OffsetLiterals .''before''
::Used to set the accessible position right before the accessible element beginning.
</code>

<code>
OffsetLiterals .''begin''
::Used to set the accessible position right after the accessible element beginning.
</code>

<code>
OffsetLiterals .''at''
::Used to set the accessible position at the accessible element.
</code>

<code>
OffsetLiterals .''end''
::Used to set the accessible position right before the accessible element ending.
</code>

<code>
OffsetLiterals .''after''
::Used to set the accessible position right after the accessible element ending.
</code>

<b>Example #1. Input widget.</b>

<pre>
<input id="input" value="Hello">
<script>
var input = document.getElementById("input").a11ement;

// Position is at the control
var p = new A11ePos(input, "at");

// Position is in the control text at 0 offset.
p = new A11ePos(input, "begin");

// Position is in the control text at 5 offset.
p = new A11ePos(input, "end");
</script>
</pre>

<b>Example #2. Image inside a paragraph.</b>

<pre>
<p id="p">I <img id="img" src="love.png" alt="love"> you</p>

<script>
var img = document.getElementById("img").a11ement;

// The position is right before the image, at 2 offset relative the paragraph.
var p = new A11ePos(img, "before");

// The position is right after the image, at 3 offset relative the paragraph.
p = new A11ePos(img, "after");

// The position is at the image, no offset relative the paragraph is applicable.
p = new A11ePos(img, "at");
p = new A11ePos(img, "begin");
p = new A11ePos(img, "end");
</script>
</pre>

<b>Example #3. Table.</b>

<pre>
<table id="table">
<tr>
<td>cell</td>
</tr>
</table>
<script>
var table = document.getElementById("table").a11ement;

// The position at the table.
var p = new A11ePos(table, "at");

// The position is in the table, before the row.
var p = new A11ePos(table, "begin");

// The position is in the table, after the row.
var p = new A11ePos(table, "end");

// The position is in the table, before the row, numeric offset is ignored.
var p = new A11ePos(table, 1);
</script>
</pre>

Construction from a point on the screen. See [[#Hit_testing|hit testing]] for details.

<code>
AccessiblePos .''Constructor''(DOMPoint, AccessibleElement)
::Constructs the accessible position.
::Parameters
:::''point'' of ''DOMPoint''
::::a point, the accessible position should be set at
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Construction from a DOM node and offset relative it. See [[#Caret_and_selection|selection]] section for examples.

<code>
AccessiblePos .''Constructor''(DOMNode, long, AccessibleElement)
::Constructs the accessible position from (DOMNode, offset) pair.
::Parameters
:::''node'' of ''DOMNode''
::::the container node
:::''offset'' of ''long''
::::offset within the container node
:::''root'' of ''AccessibleElement'', optional
::::a root of subtree containing the position. If not provided then parent document is used.
</code>

Copy constructor.

<code>
AccessiblePos .''Constructor''
::Constructs the accessible position equal to given position.
::Parameters
:::''pos'' of ''AccessiblePos''
::::accessible position to copy
</code>

====Change the position====

There is a bunch of methods to change accessible position.

<code>
AccessiblePos .''move''(AccessilbeElement, Offset)
::Move the accessible position to the given anchor and offset.
::Parameters
:::''element'' of ''AccessibleElement''
::::the anchor
:::''offset'' of ''Offsest'', optional
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMNode, long)
::Move the accessible position to the given DOM node at given offset.
::Parameters
:::''node'' of ''DOMNode''
::::the anchor
:::''offset'' of ''long''
::::offset relative the anchor
:::Return itself or null if not succeeded.

AccessiblePos .''move''(DOMPoint)
::Move the accessible position in the content. Returns true if succeeded.
::Parameters
:::''point'' of ''DOMPoint''
::::the point the accessible position should be moved to.
:::Return itself or null if not succeeded.

====Move through the content====

Accessible position can be moved through the content by criteria.

AccessiblePos .''move'' (''Where'', ''Criteria'')
::Move the accessible position to the content complying with criteria.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return itself if succeeded, otherwise null.

AccessiblePos .''search'' (''Where'', ''Criteria'')
::Search for content of the given criteria relative the accessible position.
::Parameters
:::''where'' of ''Where''
::::where the search should be performed
:::''criteria'' of ''Criteria''
::::function describing a match
:::Return new instance if succeeded, otherwise null.
</code>

=====Where to search=====

The search area and the way accessible elements are traversed are defined by <code>Where</code> argument. It defines whether traversal is perfromed by accessible tree hierarchy or by layout on the screen, and whether the traversal is relative of the current position or relative of the root.

<pre>
enum Where {
"forward",
"backward",
"cyclic forward",
"cyclic backward",
"tofirst",
"tolast",

"left",
"right",
"up",
"down",
"above",
"under",
"closest"
};
</pre>

<code>
Where .''forward''
::Search after the accessible position.

Where .''backward''
::Search backwards from the accessible position.

Where .''cyclic forward''
::Search forwards from the accessible position in cycle.

Where .''cyclic backward''
::Search backwards from the accessible position in cycle.

Where .''first''
::Search for a first match inside the root.

Where .''last''
::Search backwards (from last to first element) for a first match inside the root.

Where .''left''
::Search for a match left to the position.

Where .''right''
::Search for a match right to the position.

Where .''up''
::Search for a match up from the position.

Where .''down''
::Search for a match down from the position.

Where .''above''
::Search for a match above the position.

Where .''under''
::Search for a match under the position.

Where .''closest''
::Search for a geometrically closest match to the position.
</code>

<b>Example.</b>

<pre>
function criteria(el) { }

var pos1 = new A11ePos(new DOMPoint(x, y), a11edoc).move("forward", criteria);

var pos2 = new A11ePos(elm, "at").move("backward", criteria);

var pos3 = new A11ePos(pos).move("forward", criteria);
or
var pos2 = pos2.search("forward", criteria);
</pre>

=====Criteria=====

Criteria can be either a literal describing how the position should be moved or a matching function called for every traversed accessible.

<pre>
typedef CriteriaLiteral or CriteriaFunc Criteria;
</pre>

<pre>
enum CriteriaLiteral {
"char",
"word",
"sentence",
"line",
"paragraph",
"change",
"bit"
};
</pre>

<code>
CriteriaLiteral .''char''
::Used to move the position one char long.

CriteriaLiteral .''word''
::Used to move the position to the next word.

CriteriaLiteral .''sentence''
::Used to move the position to the next sentence.

CriteriaLiteral .''line''
::Used to move the position to beginning of next line or end of previous line.

CriteriaLiteral .''paragraph''
::Used to move the position to beginning of next/previous paragraph.

CriteriaLiteral .''change''
::Used to move the position to next change either of text attribute or new accessible.

CriteriaLiteral .''bit''
::Used to move the position to next/previous navigable position. For example, from accessible start inside of it to right before accessible outside of it or moving from end of this line to start of next line in case of soft line break lines.
</code>

<b>Example #1. Traverse a paragraph by words.</b>

<pre>
var p = document.getElementById("p").a11ement;
var pos1 = new A11ePos(p, "begin", p), pos2 = null;
while (pos2 = pos1.search("forward", "word")) {
console.log(pos2.text(pos1));
pos1 = pos2;
}
</pre>

<pre>
<p id="p">Mozilla is a <a href="">free-software</a> community which
produces the <a href="">Firefox web browser</a>.</p>
</pre>

The script above generates the log "Mozilla ", "is ", "a ", "free-", "software ", "community", "which ", "produces ", "the ", "Firefox ", "web ", "browser."

<pre>
<p id="p">Mo<a href="">zilla</a>.</p>
</pre>

The log is "Mozilla".

<pre>
callback CriteriaFunc = CriteriaLiteral or Offset or "next" (AccessibleElement);
</pre>

<code>
CriteriaFunc
::A criteria function used to define an algorithm of the match.
::Returns
:::a criteria term or offset(s)
</code>

If "next" is returned then criteria function is reentered with next traversed accessible. If offset is given then traversing is stopped, the accessible position is moved to the traversed accessible element and given offset. If criteria literal is returned then the accessible position is moved to the position complying the criteria. If it cannot be moved withing current accessible then it reenters with next accessible.

<b> Example. Navigate by widgets and structures, and by words in case of text.</b>
<pre>
function criteria(aEl)
{
var role = document.taxonOf("role", aEl.role);
if (role.is("widget")
return "at";

if (role.is("structure")
return "at";

// Reenters with next accessible if it cannot move to the next line within this accessible.
if (role.is("textcontainer"))
return "line";

return "next";
}

pos.move("next", criteria);
</pre>

====Other methods====

<code>
AccessiblePos .''root''
::Returns the accessible element the position movement is restricted to.

AccessiblePos .''anchor''
::Returns the accessible element the position is at or contained by.

AccessiblePos .''offset''
::Return an offset of the accessible position, either numeric or text.

AccessiblePos .''toDOM''
::Returns DOMRangeBound object which is a pair of DOM node and content offset relative it.
</code>

<pre>
dictionary DOMRangeBound {
DOMNode node;
long offset;
};
</pre>

===Virtual cursor===

Virtual cursor is accessible position attached to the accessible document. It's unique per document.

<pre>
partial interface AccessibleDocument {
AccesiblePos cursor;
};
</pre>

Whenever the virtual cursor position is changed then ''cursor_moved'' event is fired.

===Questions/concerns===

* Do we need *is* method right on AccessibleElement or should we have Role interface having that method or should AccessibleElement return role taxa as a role.
* Do we need to have "inContextOf" on AccessibleElement to check what the accessilbe belongs to. Note, native implementation doing some cache may be faster than tree traversal. If we need it then it's worth to consider *is* method too.
* Do we need isAnyOf() method additionally?
* Do we need to compare() method to compare two positions
* Ensure that the virtual cursor is survivable. If it ends up in the hidden sub-tree for example. If subtee gets destroyed then cursor should be moved. If AccessiblePos doesn't have matching function then it's unclear where it should be moved.
* Also take into account walking to/from parent/child frames
* Should it be outlined as moved?
* Yura: we should have async API for search.

[ Promise variant if we had async API].

<pre>
function getText() {
var p = new A11ePos().move("first", a => a.role == "paragraph");
var startPos;
return p.then(function(pos) {
startPos = pos;
return pos.search("forward", a => "line"); }).
then(function(endPos) {
return startPos.textInBetween(endPos);
};
}
getText().then(function(text) { /* Say text */ })
</pre>

==Text==

<pre>
partial interface AccessiblePos {
DOMString text(AccessiblePos pos);
DOMString text(CriteriaLiteral criteria);
readonly attribute AttributeSet textAttributes;
};
</pre>

<code>
AccessibleDocument .''text''
::Returns the text enclosed between this and given accessible positions.

AccessibleDocument .''text''
::Returns the text at the position complying the given criteria. See [[#Criteria|criteria]] for options.
</code>

Example how to get first line of the first encountered paragraph:

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var startPos = new A11ePos(document).move("first", criteria);
var endPos = startPos && startPos.search("forward", "line");
var text = startPos.text(startPos, endPos);
</pre>

or same effect by using criteria literal

<pre>
function criteria(a)
{ return a.role == "paragraph" ? "being" : "next" };
var pos = new A11ePos(document).move("first", criteria);
var text = pos.text("line");
</pre>

===Text attributes===

<code>
AccessibleDocument .''textAttributes''
::Returns a [[#AttributeSet|AttributeSet]] of all text attributes presented at this accessible position.
</code>

List of text attributes [to complete]

<code>
color
::Text color

background-color
::Background color of text
</code>

<b>Example</b>

<pre>
<p id="p">hello <b>bold</b></p>

var pos = new A11ePos(document.getElementById("p").a11ement, 7);
p.textAttributes.get("font-weight") == 700; // true
</pre>

==Caret and selection==

Document accessible provides bunch of methods to operate on text selection and caret.

<pre>
partial interface AccessibleDocument {
attribute AccessiblePos caret;
attribute AccessiblePos? selectionStart;
attribute AccessiblePos? selectionEnd;
};
</pre>

<code>
AccessibleDocument .''caret''
::Returns accessible position for the caret.
</code>

<code>
AccessibleDocument .''selectionStart''
::Get/set selection start.

AccessibleDocument .''selectionEnd''
::Get/set selection end.
</code>

<b>Example.</b>

<pre>
var pos = new A11ePos(new DOMPoint(event.x, event.y));
document.a11ement.selectionStart = pos;
var pos2 = new A11ePos(pos.anchor.nextSibling);
document.a11ement.selectionEnd = pos;
</pre>

<b>Example #2. Connection with DOM selection.</b>

<pre>
var sel = window.getSelection();
var pos1 = new A11ePos(sel.anchorNode, sel.anchorOffset);
var pos2 = new A11ePos(sel.focusNode, sel.focusOffset);

var p1 = pos1.toDOM();
sel.getRangeAt(0).setStart(p1.node, p1.offset);
var p2 = pos2.toDOM();
sel.getRangeAt(0).setEnd(p2.node, p2.offset);
</pre>

==Geometry==

The section contains bunch of methods and approaches to deal with web page geometry.

===Outline===

AT can outline a position or a range enclosed between two positions. This feature is useful to track stuff like virtual cursor.
<pre>
partial interface AccessibleDocument {
void outline(AccessiblePos pos1, optional AccessiblePos pos2);
void clearOutlines();
};
</pre>

<code>
AccessibleDocument .''outline''
::Outlines a position if second position is omitted. If second position is omitted then outlines a collapsed range.

AccessibleDocument .''clearOutlines''
::Removes all drawn outlines.
</code>

===Geometrical navigation===

AT can scan the web page by moving the position geometrically up/down/left/right.
<pre>
var scanner
{
start: function() {
if (this.stopped)
return;

var nextpos = this.pos.move("right", this.controller);
if (!nextpos)
nextpos = this.pos.move("down", this.controller);

if (nextpos) {
document.outline(nextpos);
window.setTimeout(this.start.bing(this), 1000);
}
},
stop: function() {
this.stopped = true;
},

controller: function(aEl) {
var role = document.a11ement.taxonOf("role", aElm.role);
if (role.is("widget"))
return "at";

return "next";
}
pos: new A11ePos(new DOMPoint(0, 0)),
stopped: false
}
</pre>

===Hit testing===

The author can do accessible position to match the accessible element of given criteria at given position.

<pre>
<script>
function onmove(aEvent)
{
// Announce name of the accessible element pointed by mouse.
var atcursor = new A11ePos(new DOMPoint(event.x, event.y));
say(atcursor.anchor.name);

// Locate a nearest control.
var atwidget = atcursor.search("closest", a => document.taxonOf("role", a.role).is("widget"));
if (atwidget)
say(atwidget.name);
};
</script>

<body onmove="onmove(event);></body>
</pre>

Questions/concerns
*Outline: it's tricky to style that but maybe document or accessible should decide how it should be styled, for example, black outline on black background.
*Do we need a way to return coordinates of accessible position's edge points?
*Do we need a method to calculate distance between two positions?
*Do we need a method to calculate boundaries (aka containing rect)?
*Do we need a method to check whether the given point is contained by a range?

==Events==

The accessible element may fire various number of events. You can add event listener on document accessible to handle all events from accessible elements belonging to the document.

<pre>
callback AccessibleEventListener (AccessibleEvent event);

partial interface AccessibleDocument {
void on(DOMString eventType, AccessibleEventListener listener);
void off(DOMString eventType, AccessibleEventListener listener);
};
</pre>

<code>
AccessibleDocument .''on''
::Adds event listener of the given event type.

AccessibleDocument .''off''
::Removes event listener of the given event type.
</code>

All event objects implement <code>AccessibleEvent</code> interface.

<pre>
interface AccessibleEvent {
readonly attribute DOMString type;
readonly attribute AccessibleElement target;
readonly attribute AttributeMap attributes;
};
</pre>

<code>
AccessibleEvent .''type''
::Event type.

AccessibleEvent .''target''
::Event type accessible element target.

AccessibleEvent .''attributes''
::Extra attributes used to describe the event. Used for certain event types.
</code>

<b>Example. Live regions processing.</b>

<pre>
function handleLiveRegion(aEvent)
{
var attrs =
{ live: "assertive", relevant: "change:name" };

if (aEvent.attributes.hasAllOf(attrs)) {
say(aEvent.target.name);
}
}
document.a11ement.on("change:name");
</pre>

===Event types===

[section needs to be completed]

<code>
"focus"
::Fired when accessible element is focused.

"caretmove"
::Fired when caret is moved within the document.

"change:name"
::Fired when name property is changed.
</code>

<div id="Patterns">

==Patterns==
</div>

Controls may expose own patterns to expose their semantics if it cannot be expressed by accessible element properties.

===Value controls===

Control elements having numeric value like slider, progressbar, [https://html.spec.whatwg.org/multipage/forms.html#the-meter-element meter] or numberbox implement <code>AccessibleValue</code> inteface.

<pre>
interface AccessibleValue {
readonly attribute long max;
readonly attribute long min;
readonly attribute long low;
readonly attribute long high;
readonly attribute long optimum;
readonly attribute long step;
readonly attribute long value;
};
</pre>

===Group info===

Item elements provides information about their group and their position in the group.

<pre>
interface AccessibleGroupInfo {
readonly attribute long count;
readonly attribute long index;
readonly attribute long level;
};
</pre>

===Tables===

A cell of tables and grids provide the interface for 2 dimensional navigation. Cell headers can be obtained by <code>labelledby</code> relation.

<pre>
interface AccessibleTableCell {
readonly attribute unsigned long rowIndex;
readonly attribute unsigned long colIndex;

readonly attribute unsigned long rowSpan;
readonly attribute unsigned long colSpan;
};
</pre>

<code>
AccessibleTableCell .''rowIndex''
::Return row index of the cell.

AccessibleTableCell .''colIndex''
::Return column index of the cell.
</code>

<code>
AccessibleTableCell .''rowSpan''
::Return number of rows that the cell is spanned to.

AccessibleTableCell .''colSpan''
::Return number of columns that the cell is spanned to.
</code>

==Multiprocessing==

Accessible tree is scoped to a process, i.e. you can have seamless accessible tree between all document frames until it violates security policy. In case of multiprcess frames you have to use standard mechanism to communicate between processes.

When the virtual cursor reaches a frame start or end and it was attempted to move it further then message is sent to a process where the virtual cursor would go in case of single process.

Questions/concerns
* what messaging mechanism should be used
* should it be allowed to move from iframe to parent document?

<div id="JSSource">

==Make the content accessible==
</div>

You can tweak the accessible tree right in JS. You can do both:
* extend the native semantics of the DOM element by overriding its accessible properties,
* create whole accessible trees for inaccessible content, for example, for graphics, charts in a canvas.

===Direct change of accessible properties===

Accessible element properties can be altered right on the accessible element. Changing accessible property will result in accessible events if needed. For example:

<pre>
<button id="button"></button>

<script>
var div = document.getElementById("button").a11ement;
div.name = "click me";
div.description = "test accessibility";
</script>
</pre>

Accessible name and description are changed for the accessible button, "name changed" and "description changed" events are fired. Note, it changes neither visual appearance of the button nor DOM button element properties. If affects on accessible element of the button only.

====States====

<pre>
parital interface StateSet {
void set(DOMString ... states);
void unset(DOMString ... states);
void toggle(DOMString state);
};
</pre>

<code>
StateSet .''set''
::Set given states on the accessible element.

StateSet .''unset''
::Unset given states from the accessible element.

StateSet .''toggle''
::Toggle the state on the accessible element.
</code>

<b>Example.</b>

<pre>
<div role="checkbox" onclick="disableEnable();">
<div role="listbox" id="listbox"/>

<script>
function disableEnable()
{
var listbox = document.getElementById("listbox").a11ement;
listbox.states.toggle("disabled");
}
</script>
</pre>

====Attributes====

You can add/change/delete attributes on the accessible element. For example,

<pre>
var listbox = document.getElementById("listbox").a11ement;
listbox.attributes.set("autocomplete", "list");
</pre>

====Relations====

<pre>
partial interface RelationMap {
void add(DOMString relation, AccessibleElement element);
void remove(DOMString relation, AccessibleElement element);
};
</pre>

<code>
RelationMap .''add''
::Puts the accessible element into relations.

RelationMap .''remove''
::Breaks the given relations between these accessible elements.
</code>

<pre>
var label = document.getElementById("label");
var control = document.getElementById("control").a11ement;
control.relations.add("labelledby", label.a11yment);
</pre>

====Actions====

<pre>
partial interface ActionMap {
void tweak(DOMString oldname, DOMString newname);

void add(DOMString name, object);
void delete(DOMString name);
};
</pre>

<code>
ActionMap ..''tweak''
::Toggles the action name.
</code>

<div id="AccessibleSource">

===Extend the semantic via accessible source===
</div>

Alternatively you can extend native semantic of a DOM element by connecting it to an accessible source, the object describing accessible element. If the DOM node is not accessible then setting the accessible source on it makes it accessible. Otherwise the given source lands on top of the existing accessible object.

<pre>
partial interface Node {
attribute AccessibleSource? accessibleSource;
};
</pre>

If the DOM node is accessible then you can provide accessible source by setting it up right in <code>AccessibleElement</code>.

<pre>
partial interface AccessibleElement {
attribute AccessibleSource? source;
};
</pre>

The source object used to describe the accessible element implements <code>AccessibleSource</code> interface which basically portrays properties of <code>AccessibleElement</code> interface.

<pre>
callback interface AccessibleSource {
readonly attribute DOMString role;
readonly attribute sequence<DOMString> states;

readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute DOMString value;

readonly attribute object attributes;
readonly attribute object relations;

readonly attribute sequence<DOMString> patterns;
object toPattern(DOMString);

readonly attribute DOMString text;
object textAttributesAt(Offset);

readonly attribute object actions;
void activate(DOMString action);

AccessibleElement? element;
};
</pre>

====Basics====

<code>
AccessibleSource .''role''

AccessibleSource .''states''

AccessibleSource .''name''

AccessibleSource .''description''

AccessibleSource .''value''
::These properties corresponds to properties of ''AccessibleElement'' interface.
</code>

<b>Example #1. Override accessible name of the button.</b>

If the author needs to change accessible name of the HTML button
<pre>
<button id="btn">press me</button>
</pre>

then he can do this either with ARIA
<pre>
document.getElementById("btn").setAttribute("aria-label", "new name");
</pre>

or set it directly on the accessible element
<pre>
document.getElementById("btn").a11ement.name = "new name";
</pre>

or by setting its accessible source

<pre>
document.getElementById("btn").accessibleSource = { name: "new name"; }
</pre>

These are two equivalent approaches that can be used same time and mixed with each other the way that better fits the author's intent. It's important to keep in mind though that the accessible source has a priority over ARIA attributes. Setting up the accessible source doesn't operate on DOM and thus it's supposed to be more performant as extra layer is excluded between the author and accessibility engine. Another benefit of setting the accessible source is improved code readability since the author is able to point multiple properties at once in declarative way. For example,

<pre>
<script>
document.getElementById("btn").accessibleSource = {
name: "new name",
description: "new description",
states: [ "disabled" ]
};
</script>
</pre>

====Attributes and relations====

<code>
AccessibleSource .''attributes''
::A map of attribute names and their values applied to the accessible element
AccessibleSource .''relations''
::A map of relation types and relations for this accessible element. The bunch of types may be used to point out related elements. You can use either ''Node'', ''AccessibleElement'' or ''AccessibleSource'' objects. In latter case the object has to be in the accessible tree, in other words, it has to have associated accessible element when relation is poked by AT.
</code>

<b> Example #2. Adding semantics.</b>

The accessible source can be also used when the author wants to add semantics to semantically neutral element. For example, the author can turn an ordinal HTML div element into listbox control:
<pre>
<label id="label">Names:</label>
<div id="list"></div>

<script>
var listboxSource = {
role: "listbox",
relations: {
"labelledby": [ document.getElementById("label") ]
}
};
var listboxNode = document.getElementById("list");
listboxNode.accessibleSource = listboxSource;
</script>
</pre>

It's worth to notice that accessible source approach like ARIA doesn't require the author to provide comprehensive description, i.e. correlating properties may be skipped. For example, presented <code>labelledby</code> relation makes unnecessary to provide accessible name. The browser should handle this on its own.

<b>Example #3. Lazy computations.</b>

The previous example may look bulkier than its ARIA equivalent:

<pre>
var listboxNode = document.getElementById("list");
listboxNode.setAttribute("role", "listbox");
listboxNode.setAttribute("aria-labelledby", "label");
</pre>

but its benefit is it allows accessible properties lazy computation. An accessible property whose value isn't changed during whole life cycle of its accessible element or which doesn't require an accessible event on its change is good candidate for lazy computation. For example the previous example may be modified this way:

<pre>
var listboxSource = {
role: "listbox",
relations: {
get labelledby() {
return document.querySelectorAll("*[listboxlabel]");
}
}
};
</pre>

In this case the <code>labelledby</code> relation getter is more powerful than its ARIA version and all computations are running iff somebody inquired the relation.

====Patterns====

<code>
AccessibleSource .''patterns''
::Returns a list of all patterns implemented by the accessible element.
</code>

<code>
AccessibleSource .''toPattern''
::Returns an object for the given pattern. If the method is not provided then the source object has to implemented itself all claimed patterns.
</code>

<b>Example #4. Implement patterns.</b>

<pre>
var slider = {
role: "slider",
patterns: [ "value" ],
toPattern: function(aName) {
return aName == "value" ? this : null;
},

min: 0,
max: 100,
value: 0
};
</pre>

====Text====

<code>
AccessibleSource .''text''
::Return the text.

AccessibleSource .''textAttributesAt''
::Returns object of { name: value } pairs representing text attributes at given offset within the accessible element text.
</code>

<b> Example #5. Text content.</b>

While text should be normally in the content, there are cases when the author has to provide it for non-text content. For example, this technique can be used to turn HTML image into text.

<pre>
<div id="container"></div>

<script>
var elm = document.getElementById("container");
elm.innerHTML = "I " + <img src="love.png"> + "you";

var psource = {
role: "paragraph",
text: "I love you",
textAttributesAt: function(aOffset) {
if (aOffset >= 5 && aOffset <= 7) {
return { color: "red" }; // "love" is red
}
}
};
elm.accessibleSource = psource;
</script>
</pre>

====Actions====

<code>
AccessibleSource .''actions''
::Return all supported actions on the accessible element.

AccessibleSource .''activate''
::Invoke the given action.
::Parameters
:::''action''
::::the action name to invoke
</code>

<b>Example #6. Describe actions and interactions.</b>

<pre>
function listitem(aName)
{
return {
role: "treeitem",
name: aName,
actions: {
select: {
interactions: [ { mouse: "click" } ]
}
}
};
};
</pre>

In case if interactions cannot be provided then the accessible source have to implement <code>activate</code> method to invoke actions.

====Inheritance====

<code>
AccessibleSource .''element''
::Refers to the accessible element implementation as there were no accessible source attached to it. Set by the browser when the accessible source is attached to the accessible element.
</code>

<b>Example. Lazy extension of accessible relations.</b>

<pre>
var source = {
get relations() {
var r = this.element.relations;
r.add("labelledby", document.querySelector(this.selector));
return r;
},
element: null,
selector: ""
};
document.getElementById("button").accessibleSource = source;
</pre>

===Change the accessible tree===

The web developer can alter existing accessible tree including subtree creations and deletions. This can be done either by <code>AccessibleSource</code> object assigned to the accessible element or by direct manipulations on the accessible tree.

====Direct tree alteration====

Accessible source object can be used to create new accessible element and insert it into the tree. If DOM node is used as a source then associated subtrees of accessible elements within the DOM node are reparanted, i.e. they are removed from children of its current accessible parent and added as children of new parent. Accessible element can be removed from children.

<pre>
partial interface AccessibleChildren {
void append(AccessibleSource or DOMNode ... children);
void insertBefore(AccessibleElement before, AccessibleSource or DOMNode ... children);
void insertAfter(AccessibleElement after, AccessibleSource or DOMNode ... children);
void replace(AccessibleSource or DOMNode ... children);
void remove(AccessibleElement ... children);
void clear();
};
</pre>

<code>
Children .''append''
::Appends accessible elements provided by sources as children to the accessible element.

Children .''insertBefore''
::Inserts accessible elements provided by sources before the given child.

Children .''insertAfter''
::Inserts accessible elements provided by sources after the given child.

Children .''replace''
::Replaces existing children accessible elements within elements provided by sources.

Children .''remove''
::Removes accessible elements from the accessible tree.

Children .''clear''
::Removes all child accessible elements.
</code>

<b>Example</b>

<pre>
<input id="input" role="combobox">
<div id="list" role="listbox">
<div role="listitem">choice1</div>
<div role="listitem">choice1</div>
</div>

<script>
var input = document.getElementById("input").a11ement;
input.children.replace(document.getElementById("list"));
</script>
</pre>

====Build up the tree via accessible source====

You can provide child accessible elements for the given accessible element by assigning <code>AccessibleSource</code> object to it. This approach allows to create whole portions of the accessible tree for the content having no underlying DOM nodes.

<pre>
partial interface AccessibleSource {
sequence<AccessibleSource or DOMNode> children;
};
</pre>

<code>
AccessibleSource .''children''
::Return collection of accessible children. If AccessibleSource is provided then it's used to create a new accessible element and insert it as a child. If accessible DOMNode is provided then its accessible element is used, if inaccessible DOMNode is provided then its accessible children if any are used.
</code>

<b>Example. Add list with items into the tree.</b>

<pre>
var tree = {
role: "listbox",
name: "colors",
children: [
{
role: "listitem",
states: "focusable",
name: "red"
},
{
role: "listitem",
states: "focusable",
name: "green"
}
]
};
divNode.accessibleSource = tree;
</pre>

====Canvas hit regions====

Canvas [https://html.spec.whatwg.org/multipage/scripting.html#hit-regions hit region options] are extended by ''a11ement'' which is used to connect accessible element with hit region. Whenever hit region is activated then ''activate'' method of connected ''AccessibleSource'' object is called with no argument provided.

Say you have a canvas with drawn button. In order to make it accessible you can create accessible button right in JS.

<pre>
var source = {
role: "button",
name: "test",
actions: {
click: {
interactions: {
mouse: "click"
}
}
},
onactivated: function(aEvent) {
if (aEvent.region == "button")
this.element.set("focused");
else
this.element.states.unset("focused");
}
element: null // set by the browser
};

canvasNode.addHitRegion({ id: "button", a11ement: source });
canvasNode.addEventListener("click", source.onactivated.bind(source));
</pre>

===Feedback notifications===

Accessible element may be notified of any kind of event, including about property change when managed by connected source object. When notified the browser may fire accessible events and update its cache if necessary. Decision whether to notify the browser or not should be based on the accessible events model. In other words if a property change in native markup causes accessible event then it's quite likely the event is expected for similar accessible source change.

<pre>
partial interface AccessibleElement {
void notifyOf(DOMString eventType, optional Object attrs);
};
</pre>

<code>
AccessibleElement .''notifyOf''
::Called when source has been changed to notify the host accessible element about property change. The browser is responsible to fire proper accessible events and update its internal representation.
::Parameters
:::eventType of DOMString
::::The event type to fire.
:::attrs
::::Attributes describing the event. See [[#Event_types|event types]] for attributes variety.
</code>

If the above listbox gets disabled then you have to reflect that in its state:

<pre>
var listboxSource = {
role: "listbox",
name: "breed list",
states: "disabled",

get element() { return this.elm; }
set element(aElm) {
this.elm = aElm;
this.elm.notifyOf("change:name");
this.elm.notifyOf("change:states", { added: "disabled" });
}
};

function onfocus(aEvent) {
// Change accessible properties when element is focused.
// The change requires accessible events.
aEvent.target.accessibleSource = listboxSource;
}
</pre>

===Implied semantics===

The author has to be less verbose as possible. If a role usually implies number of sets or attributes then they are supposed to set so the authur doesn't need to list them. For example if <code>listitem</code> is selectable then you don't have to point <code>selectable</code> state on it, in other words, these code snippets are equivalent:

<pre>
var source = {
role: "listitem"
};
</pre>

<pre>
var source = {
role: "listitem",
states: [ "selectable" ]
};
</pre>

The implied semantics is described by [[#SemanticsProviders|semantics provides]].

===Conflicts===

[to be done conflicts between native semantics, ARIA and this API]

===Sniffing===

In order to make optimization the content provider has to know whether accessibility consumer is active. The provider can add a callback for <code>deploy</code> and <code>conceal</code> event types which will be triggered when consumer appears/gets inactive.

<pre>
function deployA11y() {
// build accessible tree or update existing one
// keep the tree updated
}
function stopA11y() {
// stop keeping the accessible tree updated
}
document.a11ement.on("deploy", deployA11y);
document.a11ement.on("conceal", stopA11y);
</pre>

<div id="SemanticsProviders">

==Semantics providers==
</div>

The author of the content which is not a standard HTML has to provide content semantics to make the content accessible. In other words, he has to describe a semantic vocabulary that will be used to give the content specific meaning. For example, if you are ebook publisher then you will need a bunch of new roles like 'bibliography' or 'appendix'. If you do operate with complex widgets then likely you will need to describe its states, attributes or relations.

<pre>
partial interface AccessibleDocument {
void import(DOMString name, Object taxonomy);
};
</pre>

<code>
AccessibleDocument .''import''
::Import the taxonomy.
::Parameters
:::name of DOMString
::::taxonomy name like ''role'' or ''states''
:::taxonomy of Object
::::a collection of taxa and their properties.
::Throws
:::if there's names conflict or there are invalid relations between taxonomies then an exception should be thrown [todo].
</code>

Depending on [[#TaxonomyTypes|taxonomy type]], a taxa may be described by specific fields and be connected with other taxonomies. For example, DPUB semantics may be described this way:

<pre>
document.accessibleElement.import("role",
{
appendix: {
parents: "section",
landmark: "appendix",
description: "appendix"
},
bibliography: {
parents: "list",
landmark: "bibliography",
owns: "biblioentry",
description: "bibliography"
},
biblioentry: {
parents: "listitem",
description: "reference"
}
}
</pre>

This approach is alternative to [https://w3c.github.io/aria/aria/dpub.html DPUB ARIA extensions]. Any web app operating with DPUB content can import JS file describing the taxonomies and the browser can expose the content properly to the assistive technology. No special support on the browser side is required.

In short reasons to provide taxonomy are:
* The browser automatically maps the content to desktop accessibility APIs;
* The web accessibility technology knows how to expose the content;
* Adds implied accessibility support for the content;
* Automatic content validation.

<div id="Taxonomy">
===Taxonomies===
</div>

You can get hierarchical relations between roles, states, actions or anything else that has a taxonomy. For example, if the web author introduces a role 'checklistitem' which is compound from two roles 'checkbox' and 'listitem', i.e it inherits properties of both of them then the web author should integrate the new role into existing role hierarchy. Taxonomies are scoped by <code>AccessibleDocument</code> which provides bunch of methods to get them.

<pre>
partial interface AccessibleDocument {
Taxon? taxonOf(in DOMString taxonomy, in DOMString name);
Taxonomy? taxonomyOf(DOMString name);
};
</pre>

<code>
AccessibleDocument .''taxonOf''
::Returns a taxon for the given taxon name of requested taxonomy.
::Parameters
:::taxonomy
::::a taxonomy name
:::name
::::name of requested taxa like 'button' in case of 'role' taxonomy
</code>

<code>
AccessibleDocument .''taxonomyOf''
::Return an object describing requested taxonomy.
::Parameters
:::name
::::a taxonomy name
</code>

<pre>
interface Taxon {
stringifier readonly attribute DOMString name;
readonly attribute DOMString description;

readonly attribute sequence<Taxon> parentTaxa;
readonly attribute sequence<Taxon> childTaxa;

bool is(DOMString or Taxon base);

readonly attribute AttributeMap attributes;
readonly attribute RelationMap relations;
};
</pre>

<code>
Taxon .''name''
::Return name of the taxa

Taxon .''description''
::Return localized description of the taxa
</code>

<code>
Taxon .''parentTaxa''
::Return list of taxa the taxon is inherited from.

Taxon .''childTaxa''
::Return list of taxa that is inherited from this taxon.

Taxon .''is''
::Return true if given taxon name is in base of the taxon.
</code>

<code>
Taxon .''attributes''
::Return a map between attribute names and attribute values specific for the taxon.

Taxon .''relations''
::Return a map between relation types and related taxa specific for the taxon.
</code>

<b>Example #1. Handle new role as it was known.</b>
<pre>
var taxa = {
checklistitem: {
parents: [ "checkbox", "menuitem" ]
}
};
document.a11ement.import("role", taxa);
</pre>

<pre>
var taxon = document.a11ement.taxonOf("role", "checklistitem");
if (taxon.is("menuitem")) {
// process menuitem selection
}
</pre>

<b>Example #2. Checking whether role is a navigational landmark.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "main");
var isLandmark = taxon.attributes.has("landmark");
</pre>

<b>Example #3. Getting states specific to the role.</b>

<pre>
var taxon = document.a11ement.taxonOf("role", "listbox");
print(listboxRole.relations.get("states"))); // prints "focusable"
</pre>

====Managing the taxonomies====

<pre>
interface Taxonomy {
Taxon? taxonOf(DOMString name);
readonly attribute sequence<Taxon> rootTaxa;

void addTaxon(DOMString name, sequence<Taxon or DOMString> baseTaxa);
void removeTaxon(Taxon taxon);
};
</pre>

<code>
Taxonomy .''getTaxon''
::Return a taxon object for the given name.
::Parameters
:::name
::::taxon name
</code>

<code>
Taxonomy .''rootTaxa''
::Return list of base taxa
</code>

<code>
Taxonomy .''addTaxon''
::Adds new taxon into the taxonomy.
::Parameters
:::name
::::a new taxon name
:::baseTaxa
::::a list of taxa the taxon is inherited from
</code>

<code>
Taxonomy .''removeTaxon''
::Remove the given taxon and all taxa inherited from it from the taxonomy.
::Parameters
:::taxon
::::taxon object
</code>

<div id="TaxonomyTypes">

===Taxonomy types===
</div>

Each taxonomy is described means of its own interface which is used to define the hierarchy and interconnections between taxonomies. If taxon refers to taxa of other taxonomy type then a string describing the reference may be in form of "taxon:modifier", where taxon is a name of related taxon and modifier is an extra information about how the taxa are interconnected. For example, role taxon may be connected to "live" taxon of attributes taxonomy by placing "live:assertive" value in <code>attributes</code> field which means that the role supports "live" object attribute and its default value is "assertive" on it.

====Roles====

<pre>
dictionary RoleTaxon {
DOMString landmark;
DOMString description;

sequence<DOMString> parents;
sequence<DOMString> owns;
sequence<DOMString> states;
Object attributes;
};
</pre>

<code>
RoleTaxon .''landmark''
::Navigation landmark name if applicable.

RoleTaxon .''description''
::Localized role description.

RoleTaxon .''parents''
::List of roles the role is inherited from.

RoleTaxon .''owns''
::List of roles allowed in children of the role. Used for validation.

RoleTaxon .''states''
::List of states allowed on the role. Optional modifier is "default" which points out that the state is exposed on the role until explicitly specified otherwise. See [[#Implied_semantics|implied semantics]].

RoleTaxon .''attributes''
::List of attributes supported by the role. Default value of the attribute may be specified as modifier. For example, "live:polite" points out that "live" object attribute has "polite" value by default. If default value is not specified then it's taken from referred attribute taxon description.
</code>

<b>Example. ARIA <code>textbox</code> role</b>

<pre>
var taxa = {
widget: { }
input: {
parents: [ "widget" ],
states: [ "focusable:default", "focused" ]
},
textbox: {
description: "text field",
parents: [ "input" ],
states: [
"singleline:default", "multiline",
"editable", "readonly",
"required"
],
attributes: [ "autocomplete" ]
}
};
</pre>

<b>Example. ARIA <code>log</code> role.</b>

<pre>
var taxa = {
region: {
},
log: {
parents: [ "region" ],
attributes: [ "live:polite" ]
}
};
</pre>

====States====

<pre>
dictionary StateTaxon {
DOMString description;
sequence<DOMString> dependents;
DOMString opposite;
}
</pre>

<code>
StateTaxon .''description''
::Localized taxa description.

StateTaxon .''dependents''
::List of all dependent states. For example, "focused" state always accompanied by "focusable" state.

StateTaxon ..''opposite''
::An opposite state if any. Opposite state are mutually exclusive. For example, if "vertical" state is applied then "horizontal" is not and vice versa.
</code>

<b>Example.</b>

<pre>
var taxa = {
focusable: {
dependents: [ "focused" ]
},
focused: { },
singleline: {
opposite: "multiline"
},
multiline: {
opposite: "singleline"
},
readonly: { },
editable: { },
required: { }
};
</pre>

====Attributes====

<pre>
interface AttributeTaxon {
DOMString description;
sequence<DOMString> values;
DOMString default;
};
</pre>

<code>
AttributeTaxon .''description''
::Localized description of the taxon

AttributeTaxon .''values''
::List of all possible values of the attrbiute

AttributeTaxon .''default''
::Default attribute value. Takes a place if role taxa pointing to it doesn't have own default value of it.
</code>

<b>Example</b>

<pre>
var taxa = {
autocomplete: {
values: [ "none", "list", "inline", "both" ],
default: "none"
},
live: {
values: [ "none", "polite", "assertive" ],
default: "none"
}
};
</pre>

=HTML and beyond=

This doc introduces common patterns to express the semantics of markup languages to accessibility. Markup specifics is not a target for this doc in general. Each markup specification has to take care to describe their accessibility stuff in terms of this API.

=Extensibility=

The web application might need to extend default taxonomies to express the new semantics. For example, the web service publishing music sheets can introduce new characteristics like role, states, etc to describe music sheet content. However the web application should take care to explain new characteristic by extending default taxonomies, i.e. by describing the connection between old and new characteristics. That will resolve any backward compatibility issue, so if the consumer doesn't know about new roles then he can still figure out a closest match it's aware about. For example, if the web app author introduces "x-redbutton' and provides a role taxonomy for it saying this is an extension of 'button' role, then the consumer unfamiliar with 'x-redbutton' role will treat it as a button.

The author should follow name convention to avoid potential collisions with future additions into the spec predefined lists. Thus all names should be prefixed by 'x-' like 'x-redbutton' from example above.

==Music sheet example==

To make a music sheet accessible the web app may introduce bunch of new roles, attributes and relations:

<pre>
roles:
'sheet' - inherited from 'section'
'note' - inherited from 'image', describes the note
</pre>

<pre>
role 'sheet' attributes:
instrument: DOMString,
tempo: number/DOMString
clef: DOMString
</pre>

<pre>
role 'note' attributes:
key: enum { C, D, E, F, G, A, H },
alteration: enum { none, flat, sharp },
octave: enum { ... },
duration: number,
effects: sequence<DOMString>, // tremolo, bend
</pre>

<pre>
role 'note' relations:
crescendo: [note, ...] a list a notes the crescendo is applied to
diminuendo: [note, ...] a list a notes the diminuendo is applied to
</pre>