├── src
    ├── .eslintignore
    ├── .eslintrc.js
    ├── DOMTraversal.js
    └── focus-traversal-api-polyfill.js
├── .gitignore
├── examples
    ├── WebComponents
    │   ├── focus-example.html
    │   ├── focus-example.css
    │   ├── focus-example.js
    │   ├── index.html
    │   └── zeph.min.js
    └── BasicFocus
    │   └── index.html
├── jsdoc.json
├── LICENSE
├── GET_INVOLVED.md
├── package.json
├── RELEASE_NOTES.md
├── CODE_OF_CONDUCT.md
├── PROPOSAL.md
├── README.md
├── focus-traversal-api-polyfill.min.js
├── TheCaseForFocus.md
├── test
    └── DOMTraversalTest.js
├── EXPLAINER.md
└── focus-traversal-api-polyfill.full.js


/src/.eslintignore:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | 


--------------------------------------------------------------------------------
/examples/WebComponents/focus-example.html:
--------------------------------------------------------------------------------
1 | <div>
2 | 	<label></label>
3 | 	<input type="text" value=""></input>
4 | </div>
5 | 


--------------------------------------------------------------------------------
/examples/WebComponents/focus-example.css:
--------------------------------------------------------------------------------
 1 | :host {
 2 | 	display: block;
 3 | 	font-family: sans-serif;
 4 | 	padding: 10px 10px;
 5 | 	width: 100%;
 6 | }
 7 | 
 8 | label {
 9 | 	display: block;
10 | 	font-size: 14px;
11 | }
12 | 
13 | input {
14 | 	display: block;
15 | 	width: 93%;
16 | 	font-size: 18px;
17 | 	font-weight: bold;
18 | 	padding: 3px 5px;
19 | 	border-radius: 5px 0px 5px 0px;
20 | 	border: 2px solid black;
21 | 	outline: none;
22 | }
23 | 
24 | input.highlight {
25 | 	background: #FFFFAA;
26 | }
27 | 
28 | input:focus {
29 | 	background: #AAFFAA;
30 | }
31 | 


--------------------------------------------------------------------------------
/src/.eslintrc.js:
--------------------------------------------------------------------------------
 1 | "use strict";
 2 | 
 3 | module.exports = {
 4 | 	"extends": "eslint:recommended",
 5 | 	parserOptions: {
 6 | 		ecmaVersion: 6
 7 | 	},
 8 |     env: {
 9 |         es6: true,
10 | 		browser: true
11 |     },
12 |     rules: {
13 | 		"no-self-assign": [
14 | 			"off"
15 | 		],
16 |         indent: [
17 |             "error",
18 |             "tab",
19 | 			{ "SwitchCase": 1 }
20 |         ],
21 |         semi: [
22 |             "error",
23 |             "always"
24 |         ],
25 | 		"require-await": [
26 | 			"error"
27 | 		],
28 | 		"no-constant-condition": [
29 | 			"off"
30 | 		]
31 |     }
32 | };
33 | 


--------------------------------------------------------------------------------
/examples/WebComponents/focus-example.js:
--------------------------------------------------------------------------------
 1 | // (c) 2018-present, The Awesome Engineering Company, https://awesomeneg.com
 2 | 
 3 | import {ZephComponents,html,css,attribute,bind,bindAt,onAdd} from "./zeph.min.js";
 4 | 
 5 | ZephComponents.define("focus-example",()=>{
 6 | 	html("./focus-example.html");
 7 | 	css("./focus-example.css");
 8 | 
 9 | 	attribute("label","");
10 | 
11 | 	bind("@label","label","$");
12 | 	bind("$","input","@value");
13 | 	bind("@value",".",".value");
14 | 	bindAt("input",".value",".","@value");
15 | 
16 | 	onAdd((element,children)=>{
17 | 		let target = children.querySelector("input");
18 | 		focusManager.proxy(element,target);
19 | 	});
20 | });
21 | 


--------------------------------------------------------------------------------
/jsdoc.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "env": {
 3 |         "conf": {
 4 |             "plugins": [],
 5 |             "recurseDepth": 10,
 6 |             "source": {
 7 |                 "includePattern": ".+\\.js(doc|x)?$",
 8 |                 "excludePattern": "(^|\\/|\\\\)_"
 9 |             },
10 |             "sourceType": "module",
11 |             "tags": {
12 |                 "allowUnknownTags": true,
13 |                 "dictionaries": [
14 |                     "jsdoc",
15 |                     "closure"
16 |                 ]
17 |             },
18 |             "templates": {
19 |                 "monospaceLinks": false,
20 |                 "cleverLinks": false,
21 |                 "default": {
22 |                     "outputSourceFiles": true
23 |                 }
24 |             }
25 |         }
26 |     }
27 | }
28 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2019 Awesome Engineering
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/GET_INVOLVED.md:
--------------------------------------------------------------------------------
 1 | # Focus Traversal API
 2 | 
 3 | We are always looking for people to get involved with the Focus Traversal API and proposal. Please consider helping us out in one of the following ways...
 4 | 
 5 | #### Spread the word!
 6 | 
 7 | [Tweet and Retweet](https://ctt.ac/H1IoF) about our proposal.
 8 | 
 9 | Make sure to use the hashtag [#FocusTraversalAPI](https://twitter.com/search?q=%23FocusTraversalAPI&src=typd)!
10 | 
11 | #### Comment on the Proposal.
12 | 
13 | You can comment in either the [WICG W3C Proposal Submission discourse](https://discourse.wicg.io/t/proposal-focus-traversal-api/3427), or the [WHATWG Github Issue](https://github.com/whatwg/html/issues/4784). Even a thumbs up helps!
14 | 
15 | Also, google has an incubator system for additions to chromium to which a ticket was submitted: https://bugs.chromium.org/p/chromium/issues/detail?id=997446
16 | 
17 | #### Download the Polyfill and use it
18 | 
19 | The more people [use the polyfill](./README.md#focus-traversal-api), the more issues we can find, and the more solid our proposal becomes.
20 | 
21 | You can get started using it today with npm!
22 | 
23 | ```
24 | npm install focus-traversal-api-polyfill
25 | ```
26 | 
27 | #### Participate
28 | 
29 | We need people to actively help us out, write test, make the proposal better.  Take a look at the [issues](https://github.com/awesomeeng/FocusTraversalAPI/issues) for an idea of where to get started!
30 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "focus-traversal-api-polyfill",
 3 |   "version": "2.1.1",
 4 |   "author": "the awesome engineering company",
 5 |   "license": "MIT",
 6 |   "contributors": [
 7 |     "Glen R. Goodwin"
 8 |   ],
 9 |   "main": "./polyfill/web-focus-api-polyfill.js",
10 |   "dependencies": {},
11 |   "devDependencies": {
12 |     "jsdom": "^15.2.0",
13 |     "eslint": "5.16.0",
14 |     "jsdoc-to-markdown": "^5.0.2",
15 |     "minify": "4.1.1",
16 |     "mocha": "^6.2.2"
17 |   },
18 |   "optionalDependencies": {},
19 |   "scripts": {
20 |     "lint": "eslint src",
21 |     "docs": "jsdoc2md src/** --separators > docs/API.md",
22 |     "test": "mocha test",
23 |     "tests": "mocha test",
24 |     "minify": "cat src/DOMTraversal.js src/focus-traversal-api-polyfill.js > focus-traversal-api-polyfill.full.js && minify focus-traversal-api-polyfill.full.js > focus-traversal-api-polyfill.min.js",
25 |     "dev": "nodemon -w src --exec \"npm run minify && node /mnt/c/DEV/Awesome/Code/zephjs/src/cli/CLI.js serve\""
26 |   },
27 |   "description": "Focus Traversal API polyfill.",
28 |   "directories": {
29 |     "doc": "docs",
30 |     "test": "test"
31 |   },
32 |   "repository": {
33 |     "type": "git",
34 |     "url": "git+https://github.com/awesomeeng/FocusTraversalAPI.git"
35 |   },
36 |   "keywords": [
37 |     "focus",
38 |     "focus traversal",
39 |     "focus api",
40 |     "focus traversal api",
41 |     "traversal api",
42 |     "browser focus",
43 |     "browser focus api",
44 |     "browser focus traversal api",
45 |     "web focus",
46 |     "web focus api",
47 |     "web focus traversal api"
48 |   ],
49 |   "bugs": {
50 |     "url": "https://github.com/awesomeeng/FocusTraversalAPI/issues"
51 |   },
52 |   "homepage": "https://github.com/awesomeeng/FocusTraversalAPI#readme"
53 | }
54 | 


--------------------------------------------------------------------------------
/RELEASE_NOTES.md:
--------------------------------------------------------------------------------
 1 | # AwesomeComponenets Release Notes
 2 | 
 3 | #### **Version 2.1.1**
 4 | 
 5 |  - Fixes a bunch of error introduced accidentally with 2.1.0. Sorry.
 6 | 
 7 | #### **Version 2.1.0**
 8 | 
 9 |  - Removes tabbable dependency.
10 |  - trap() and untrap() can now take more than one element argument.
11 | 
12 | #### **Version 2.0.4**
13 | 
14 |  - Fixes bug in `untrap()` that would cause an exception if called with no traps set.
15 | 
16 | 
17 | #### **Version 2.0.2**
18 | 
19 |  - Adds the `parent()` and `child()` methods.
20 | 
21 | #### **Version 2.0.1**
22 | 
23 |  - Moved jsdom to devDependencies.
24 | 
25 | #### **Version 2.0.0**
26 | 
27 |  - Adds `order()` method to programatically set the focus order of one or elements.
28 |  - Adds `trap()` and `untrap()` to control trapping focus into a given container.
29 |  - Adds `proxy()` and `unproxy()` to easily forward focus from one element to another.
30 |  - Renamed `orderedElements()` to `list()`.
31 |  - Fixes a bug in traversal that was preventing shadow elements from traversing backwards correctly.
32 |  - DOMTraversal code broken out into a separate file and refactored. (This will move to a future project at some point.)
33 |  - Lots of bug fixes around focus and shadowroot behaviors.
34 |  - Revised next() and previous() behavior.
35 |  - Removed dependency on Tabable.
36 | 
37 | #### **Version 1.2.0**
38 | 
39 |  - Adds focusOption argument to focusManager.focus(), focusManager.forward() and focusManager.backward to align with element.focus.
40 | 
41 |  - Adds container constraint to focusManager.orderedElements().
42 | 
43 |  - Adds focusManager.first() and focusManager.last() for finding the first focusable or last focusable in a given container.
44 | 
45 | #### **Version 1.1.0**
46 | 
47 |  - Adds support for focus traversal into and out of a Shadow DOM element.
48 | 
49 | #### **Version 1.0.1**
50 | 
51 |  - Adds Minified version.
52 | 
53 | #### **Version 1.0.0**
54 | 
55 |  - Initial release.
56 | 


--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
 1 | # Contributor Covenant Code of Conduct
 2 | 
 3 | ## Our Pledge
 4 | 
 5 | In the interest of fostering an open and welcoming environment, we as
 6 | contributors and maintainers pledge to making participation in our project and
 7 | our community a harassment-free experience for everyone, regardless of age, body
 8 | size, disability, ethnicity, sex characteristics, gender identity and expression,
 9 | level of experience, education, socio-economic status, nationality, personal
10 | appearance, race, religion, or sexual identity and orientation.
11 | 
12 | ## Our Standards
13 | 
14 | Examples of behavior that contributes to creating a positive environment
15 | include:
16 | 
17 | * Using welcoming and inclusive language
18 | * Being respectful of differing viewpoints and experiences
19 | * Gracefully accepting constructive criticism
20 | * Focusing on what is best for the community
21 | * Showing empathy towards other community members
22 | 
23 | Examples of unacceptable behavior by participants include:
24 | 
25 | * The use of sexualized language or imagery and unwelcome sexual attention or
26 |   advances
27 | * Trolling, insulting/derogatory comments, and personal or political attacks
28 | * Public or private harassment
29 | * Publishing others' private information, such as a physical or electronic
30 |   address, without explicit permission
31 | * Other conduct which could reasonably be considered inappropriate in a
32 |   professional setting
33 | 
34 | ## Our Responsibilities
35 | 
36 | Project maintainers are responsible for clarifying the standards of acceptable
37 | behavior and are expected to take appropriate and fair corrective action in
38 | response to any instances of unacceptable behavior.
39 | 
40 | Project maintainers have the right and responsibility to remove, edit, or
41 | reject comments, commits, code, wiki edits, issues, and other contributions
42 | that are not aligned to this Code of Conduct, or to ban temporarily or
43 | permanently any contributor for other behaviors that they deem inappropriate,
44 | threatening, offensive, or harmful.
45 | 
46 | ## Scope
47 | 
48 | This Code of Conduct applies within all project spaces, and it also applies when
49 | an individual is representing the project or its community in public spaces.
50 | Examples of representing a project or community include using an official
51 | project e-mail address, posting via an official social media account, or acting
52 | as an appointed representative at an online or offline event. Representation of
53 | a project may be further defined and clarified by project maintainers.
54 | 
55 | ## Enforcement
56 | 
57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
58 | reported by contacting the project team at contrib@awesomeeng.com. All
59 | complaints will be reviewed and investigated and will result in a response that
60 | is deemed necessary and appropriate to the circumstances. The project team is
61 | obligated to maintain confidentiality with regard to the reporter of an incident.
62 | Further details of specific enforcement policies may be posted separately.
63 | 
64 | Project maintainers who do not follow or enforce the Code of Conduct in good
65 | faith may face temporary or permanent repercussions as determined by other
66 | members of the project's leadership.
67 | 
68 | ## Attribution
69 | 
70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
72 | 
73 | [homepage]: https://www.contributor-covenant.org
74 | 
75 | For answers to common questions about this code of conduct, see
76 | https://www.contributor-covenant.org/faq
77 | 
78 | 


--------------------------------------------------------------------------------
/PROPOSAL.md:
--------------------------------------------------------------------------------
 1 | # Focus Traversal API
 2 | 
 3 | The current system for programmatically manipulating focus within a web page leaves a lot to be desired. A single element can request the focus with the `focus()` method but that is the extent of the programatic focus navigation options.  Advancing the focus to the next focusable element or the previous focusable element involves a complex dance of DOM traversal and guess work as to what elements can recieve focus or not.  Most solutions to manipulating focus are complicated; the very simple need to manipulate focus in a meaningful and accessalbe manner is significantly lacking.
 4 | 
 5 | ## Proposed
 6 | 
 7 | The creation of a unified Focus Traversal API that makes understanding, manipulating, and traversing the focus simple.  This must include the ability to assign the focus, move the focus forward and backward, and understand both the next and previous focusable elements.
 8 | 
 9 | A rough example of this API might be the following:
10 | 
11 | `window.focusManager.currentlyFocused` - Contains the element currently holding the focus, if any.
12 | 
13 | `window.focusManager.previouslyFocused` - Contains the element that held the focus prior to the current focus, if any.
14 | 
15 | `window.focusManager.history` - An array of the last n historical focus holders.
16 | 
17 | `window.focusManager.isFocusable(element)` - Returns true if the given element can receive the focus.
18 | 
19 | `window.focusManager.hasFocus(element)` - Returns true if the given element currently has the focus.  Functionally equivelent to `window.focusManager.currentlyFocused===element`.
20 | 
21 | `window.focusManager.focus(element)` - Focus on the given element. Functionally the same as `element.focus()`. Returns void.
22 | 
23 | `window.focusManager.forward()` - Move the focus to the next focusable element.  Returns void.
24 | 
25 | `window.focusManager.backward()` - Move the focus to the previous focusable element.  Returns void.
26 | 
27 | `window.focusManager.next(element)` - Returns the element that would revieve the focus if `window.focusManager.forward()` was called when the given element has the focus.  If no element is given, the currently focused element is used.
28 | 
29 | `window.focusManager.previous(element)` - Returns the element that would revieve the focus if `window.focusManager.backward()` was called when the given element has the focus.  If no element is given, the currently focused element is used.
30 | 
31 | `window.focusManager.list()` - Returns an array of all focusable elements in the order that focus traversal would occur.
32 | 
33 | `window.focusManager.order(element,element,element,etc)` - Programatically set the traversal order of one or more elements. Given an array of elements (or multiple arguments) order them in the order they are given.
34 | 
35 | `window.focusManager.trap()` - Trap focus within a given element, such that any focus event outside of the element's descendants will refocus the last focused element within the element's descendants. Traps calls stack, such that the latest trap always wins, but removing a trap will set th enext prior trap running.
36 | 
37 | `window.focusManager.untrap()` - Removes a trap.
38 | 
39 | `window.focusManager.proxy(source,target)` - When the given source element receives the focus, forward that focus immediately to the target element.
40 | 
41 | `window.focusManager.unproxy(source,target)` - Removes a proxy.
42 | 
43 | ## Illustrative User Issues
44 | 
45 |  - https://stackoverflow.com/questions/7208161/focus-next-element-in-tab-index
46 |  - https://stackoverflow.com/questions/3639908/retrieving-previously-focused-element
47 | 
48 | ## Example Polyfill
49 | 
50 | An example implementation of the above as well as this document can be found at https://github.com/awesomeeng/FocusTraversalAPI.
51 | 
52 | ## Similar Works
53 | 
54 | https://github.com/davidtheclark/tabbable - A very popular library for getting a list of all the elements in a element that can recieve the focus.
55 | 


--------------------------------------------------------------------------------
/examples/WebComponents/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html lang="en" dir="ltr">
  3 | <meta charset="utf-8">
  4 | 	<head>
  5 | 		<meta charset="utf-8">
  6 | 		<title>WebComponents - Examples - FocusTraversalAPI</title>
  7 | 		<script src="../../focus-traversal-api-polyfill.full.js" type="text/javascript"></script>
  8 | 		<script src="./focus-example.js" type="module"></script>
  9 | 		<style>
 10 | 			body {
 11 | 				font-family: sans-serif;
 12 | 				font-size: 18px;
 13 | 			}
 14 | 			.container {
 15 | 				margin: 10px;
 16 | 				padding: 10px;
 17 | 				border: 1px solid #888;
 18 | 				width: 400px;
 19 | 			}
 20 | 
 21 | 			.field {
 22 | 				padding: 5px;
 23 | 				width: 100%;
 24 | 			}
 25 | 
 26 | 			.field > label {
 27 | 				display: block;
 28 | 				font-size: smaller;
 29 | 				font-weight: bold;
 30 | 			}
 31 | 
 32 | 			.field > input {
 33 | 				display: block;
 34 | 				width: 96%;
 35 | 				padding: 3px 5px;
 36 | 			}
 37 | 
 38 | 			.field > input.highlight {
 39 | 				background: #FFFFAA;
 40 | 			}
 41 | 
 42 | 			.field > input:focus {
 43 | 				background: #AAFFAA;
 44 | 			}
 45 | 
 46 | 			.buttons {
 47 | 				padding: 5px;
 48 | 			}
 49 | 
 50 | 			.buttons > * {
 51 | 				padding: 0px 10px;
 52 | 				margin-bottom: 5px;
 53 | 			}
 54 | 		</style>
 55 | 	</head>
 56 | 	<body>
 57 | 		<div class="container">
 58 | 			<div class="field">
 59 | 				<label>Your Name?</label>
 60 | 				<input type="text" autofocus>
 61 | 			</div>
 62 | 		</div>
 63 | 		<div class="container">
 64 | 			<focus-example label="Favorite Bob's Burgers Character?">Louise Belcher</focus-example>
 65 | 			<focus-example label="Favorite Simpsons Character?"></focus-example>
 66 | 			<focus-example label="Favorite Family Guy Character?">Brian</focus-example>
 67 | 			<focus-example label="Favorite Archer Character?">Archer Sterling</focus-example>
 68 | 		</div>
 69 | 		<div class="container">
 70 | 			<div class="buttons">
 71 | 				<button id="first" tabindex="-1">Focus First</button>
 72 | 				<button id="backward" tabindex="-1">Focus Backward</button>
 73 | 				<button id="forward" tabindex="-1">Focus Forward</button>
 74 | 				<button id="last" tabindex="-1">Focus Last</button>
 75 | 				<button id="list" tabindex="-1">Focus List</button>
 76 | 				<button id="prev" tabindex="-1">Highlight Previous Focus</button>
 77 | 				<button id="next" tabindex="-1">Highlight Next Focus</button>
 78 | 			</div>
 79 | 		</div>
 80 | 		<script>
 81 | 			var first = document.body.querySelector("#first");
 82 | 			var backward = document.body.querySelector("#backward");
 83 | 			var forward = document.body.querySelector("#forward");
 84 | 			var last = document.body.querySelector("#last");
 85 | 			var list = document.body.querySelector("#list");
 86 | 			var next = document.body.querySelector("#next");
 87 | 			var prev = document.body.querySelector("#prev");
 88 | 			var highlighted = null;
 89 | 
 90 | 			var removeHighlight = function() {
 91 | 				if (highlighted) highlighted.className = "";
 92 | 				highlighted = null;
 93 | 			};
 94 | 
 95 | 			var undoButtonFocus = function() {
 96 | 				focusManager.focus(focusManager.previouslyFocused,true);
 97 | 			};
 98 | 
 99 | 			first.addEventListener("click",function(event){
100 | 				removeHighlight();
101 | 				undoButtonFocus();
102 | 
103 | 				var first = focusManager.first(document.body);
104 | 				if (first) focusManager.focus(first);
105 | 			});
106 | 
107 | 			backward.addEventListener("click",function(event){
108 | 				removeHighlight();
109 | 				undoButtonFocus();
110 | 				focusManager.backward();
111 | 			});
112 | 
113 | 			forward.addEventListener("click",function(event){
114 | 				removeHighlight();
115 | 				undoButtonFocus();
116 | 				focusManager.forward();
117 | 			});
118 | 
119 | 			last.addEventListener("click",function(event){
120 | 				removeHighlight();
121 | 				undoButtonFocus();
122 | 
123 | 				var last = focusManager.last(document.body);
124 | 				if (last) focusManager.focus(last);
125 | 			});
126 | 
127 | 			list.addEventListener("click",function(event){
128 | 				undoButtonFocus();
129 | 				console.log(focusManager.list());
130 | 			});
131 | 
132 | 			next.addEventListener("click",function(event){
133 | 				removeHighlight();
134 | 				undoButtonFocus();
135 | 				highlighted = focusManager.next();
136 | 				if (highlighted) highlighted.className = "highlight";
137 | 			});
138 | 
139 | 			prev.addEventListener("click",function(event){
140 | 				removeHighlight();
141 | 				undoButtonFocus();
142 | 				highlighted = focusManager.previous();
143 | 				if (highlighted) highlighted.className = "highlight";
144 | 			});
145 | 		</script>
146 | 	</body>
147 | </html>
148 | 


--------------------------------------------------------------------------------
/examples/BasicFocus/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html lang="en" dir="ltr">
  3 | 	<head>
  4 | 		<meta charset="utf-8">
  5 | 		<title>BasicFocus - Examples - FocusTraversalAPI</title>
  6 | 		<script src="../../focus-traversal-api-polyfill.full.js" type="text/javascript"></script>
  7 | 		<style>
  8 | 			body {
  9 | 				font-family: sans-serif;
 10 | 				font-size: 18px;
 11 | 			}
 12 | 			.container {
 13 | 				margin: 10px;
 14 | 				padding: 10px;
 15 | 				border: 1px solid #888;
 16 | 				width: 400px;
 17 | 			}
 18 | 
 19 | 			.field {
 20 | 				padding: 5px;
 21 | 				width: 100%;
 22 | 			}
 23 | 
 24 | 			.field > label {
 25 | 				display: block;
 26 | 				font-size: smaller;
 27 | 				font-weight: bold;
 28 | 			}
 29 | 
 30 | 			.field > input {
 31 | 				display: block;
 32 | 				width: 93%;
 33 | 				padding: 3px 5px;
 34 | 			}
 35 | 
 36 | 			.field > input.highlight {
 37 | 				background: #FFFFAA;
 38 | 			}
 39 | 
 40 | 			.field > input:focus {
 41 | 				background: #AAFFAA;
 42 | 			}
 43 | 
 44 | 			.buttons {
 45 | 				padding: 5px;
 46 | 			}
 47 | 
 48 | 			.buttons > * {
 49 | 				padding: 0px 10px;
 50 | 				margin-bottom: 5px;
 51 | 			}
 52 | 		</style>
 53 | 	</head>
 54 | 	<body>
 55 | 		<div class="container">
 56 | 			<div class="field">
 57 | 				<label for"t1">First Name</label>
 58 | 				<input type="text"></input>
 59 | 			</div>
 60 | 			<div class="field">
 61 | 				<label for"t1">Last Name</label>
 62 | 				<input type="text"></input>
 63 | 			</div>
 64 | 			<div class="field">
 65 | 				<label for"t1">Address 1</label>
 66 | 				<input type="text"></input>
 67 | 			</div>
 68 | 			<div class="field">
 69 | 				<label for"t1">City</label>
 70 | 				<input type="text"></input>
 71 | 			</div>
 72 | 			<div class="field">
 73 | 				<label for"t1">State/Province</label>
 74 | 				<input type="text"></input>
 75 | 			</div>
 76 | 			<div class="field">
 77 | 				<label for"t1">Postal Code</label>
 78 | 				<input type="text"></input>
 79 | 			</div>
 80 | 			<div class="buttons">
 81 | 				<button id="first" tabindex="-1">Focus First</button>
 82 | 				<button id="backward" tabindex="-1">Focus Backward</button>
 83 | 				<button id="forward" tabindex="-1">Focus Forward</button>
 84 | 				<button id="last" tabindex="-1">Focus Last</button>
 85 | 				<button id="list" tabindex="-1">Focus List</button>
 86 | 				<button id="prev" tabindex="-1">Highlight Previous Focus</button>
 87 | 				<button id="next" tabindex="-1">Highlight Next Focus</button>
 88 | 			</div>
 89 | 		</div>
 90 | 		<script>
 91 | 			var first = document.body.querySelector("#first");
 92 | 			var backward = document.body.querySelector("#backward");
 93 | 			var forward = document.body.querySelector("#forward");
 94 | 			var last = document.body.querySelector("#last");
 95 | 			var list = document.body.querySelector("#list");
 96 | 			var next = document.body.querySelector("#next");
 97 | 			var prev = document.body.querySelector("#prev");
 98 | 
 99 | 			var removeHighlight = function() {
100 | 				document.body.querySelectorAll("input").forEach(function(e){
101 | 					e.className = "";
102 | 				});
103 | 			};
104 | 
105 | 			first.addEventListener("click",function(event){
106 | 				removeHighlight();
107 | 				focusManager.focus(focusManager.previouslyFocused,true);
108 | 
109 | 				var first = focusManager.first(document.body);
110 | 				if (first) focusManager.focus(first);
111 | 			});
112 | 
113 | 			backward.addEventListener("click",function(event){
114 | 				removeHighlight();
115 | 				focusManager.focus(focusManager.previouslyFocused,true);
116 | 				focusManager.backward();
117 | 			});
118 | 
119 | 			forward.addEventListener("click",function(event){
120 | 				removeHighlight();
121 | 				focusManager.focus(focusManager.previouslyFocused,true);
122 | 				focusManager.forward();
123 | 			});
124 | 
125 | 			last.addEventListener("click",function(event){
126 | 				removeHighlight();
127 | 				focusManager.focus(focusManager.previouslyFocused,true);
128 | 
129 | 				var last = focusManager.last(document.body);
130 | 				if (last) focusManager.focus(last);
131 | 			});
132 | 
133 | 			list.addEventListener("click",function(event){
134 | 				focusManager.focus(focusManager.previouslyFocused,true);
135 | 				console.log(focusManager.list());
136 | 			});
137 | 
138 | 			next.addEventListener("click",function(event){
139 | 				removeHighlight();
140 | 				focusManager.focus(focusManager.previouslyFocused,true);
141 | 				var target = focusManager.next();
142 | 				if (target) target.className = "highlight";
143 | 			});
144 | 
145 | 			prev.addEventListener("click",function(event){
146 | 				removeHighlight();
147 | 				focusManager.focus(focusManager.previouslyFocused,true);
148 | 				var target = focusManager.previous();
149 | 				if (target) target.className = "highlight";
150 | 			});
151 | 		</script>
152 | 	</body>
153 | </html>
154 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Focus Traversal API
 2 | 
 3 | The Focus Traversal API is a proposed change to the W3C/wHATWG HTML Specification for making working with Browser UI Focus more useful and more powerful.  The proposal has been brought to the [W3C WICG](https://discourse.wicg.io/t/proposal-focus-traversal-api/3427) and the [WHATWG](https://github.com/whatwg/html/issues/4784) for discussion and hopefully implementation and is currently in the discussion phase within both communities. If you would like more details about the proposal, an EXPLAINER is provided at: [EXPLAINER](./EXPLAINER.md)
 4 | 
 5 | Additionally, a polyfill for the proposed additions can be found here to allow the community to try and demonstrate the usefulness of Focus Traversal and we encourage everyone to give it a try.
 6 | 
 7 | Also, we are always looking for people to get involved with the Focus Traversal API and proposal. Please consider helping us by spreading the word, commenting on the proposal, or participating in this repo!
 8 | 
 9 | Check out our [GETTING INVOLVED page](./GET_INVOLVED.md) for more details on how you can help!
10 | 
11 | ## Focus Traversal API Features
12 | 
13 |  - Implements proposed Focus Traversal API standard.
14 |  - Programatically move the focus forward or backwards.
15 |  - Identify the next and previous items to receive focus.
16 |  - Supports handling focus in Shadow DOM hidden components.
17 |  - History of the last n focus holders.
18 |  - Works on all modern browsers including Internet Explorer 9 or later.
19 | 
20 | ## Usage
21 | 
22 | Install from npm...
23 | 
24 | ```
25 | npm install focus-traversal-api-polyfill
26 | ```
27 | 
28 | Copy the polyfill into your own project...
29 | 
30 | ```shell
31 | cp focus-traversal-api-polyfill/focus-traversal-api-polyfill.min.js .
32 | ```
33 | 
34 | Include in your index.html...
35 | 
36 | ```
37 | <script src="./focus-traversal-api-polyfill.min.js" type="text/javascript"></script>
38 | ```
39 | 
40 | You may now use the focusManager as described in the section below.
41 | 
42 | ## API Documentation
43 | 
44 | > `window.focusManager.currentlyFocused` - Contains the element currently holding the focus, if any.
45 | 
46 | > `window.focusManager.previouslyFocused` - Contains the element that held the focus prior to the current focus, if any.
47 | 
48 | > `window.focusManager.history` - An array of the last n historical focus holders.
49 | 
50 | > `window.focusManager.historyLimit` - A number indicating how may focus history events should be retained. Defaults to 50.
51 | 
52 | > `window.focusManager.isFocusable(element)` - Returns true if the given element can receive focus.
53 | 
54 | > `window.focusManager.hasFocusable(element)` - Returns true if the given element currently has the focus.
55 | 
56 | > `window.focusManager.focus(element,focusOption)` - Focus on the given element. Functionally the same as `element.focus()`. Returns void.
57 | 
58 | > `window.focusManager.forward(focusOption)` - Move the focus to the next focusable element.  Returns void.
59 | 
60 | > `window.focusManager.backward(focusOption)` - Move the focus to the previous focusable element.  Returns void.
61 | 
62 | > `window.focusManager.next(element)` - Returns the element that would receive the focus if `window.focusManager.forward()` was called when the given element has the focus.  If no element is given, the currently focused element is used.
63 | 
64 | > `window.focusManager.previous(element)` - Returns the element that would receive the focus if `window.focusManager.backward()` was called when the given element has the focus.  If no element is given, the currently focused element is used.
65 | 
66 | > `window.focusManager.list(container)` - Returns an array of all focusable elements in the order that focus traversal would occur. If container is provided and a valid HTMLElement, this would limit the results to only the children of the given container. If no container is provided, the current document is used as the container.
67 | 
68 | > `window.focusManager.first(container)` - Returns the first element that would receive focus for the given container, or the current document if no container is provided.
69 | 
70 | > `window.focusManager.last(container)` - Returns the first element that would receive focus for the given container, or the current document if no container is provided.
71 | 
72 | > `window.focusManager.parent(element)` - returns the first focusable ancestor of the given element.
73 | 
74 | > `window.focusManager.child(element)` - returns the first focusable descendant of the given element. The same as `first(element)`.
75 | 
76 | > `window.focusManager.order(element,element,element,etc)` - Programatically set the traversal order of one or more elements. Given an array of elements (or multiple arguments) order them in the order they are given.
77 | 
78 | > `window.focusManager.trap()` - Trap focus within a given element(s), such that any focus event outside and of the given element(s) descendants will refocus the last focused element within the element's descendants. Traps calls stack, such that the latest trap always wins, but removing a trap will set th enext prior trap running.
79 | 
80 | > `window.focusManager.untrap()` - Removes a trap.
81 | 
82 | > `window.focusManager.proxy(source,target)` - When the given source element receives the focus, forward that focus immediately to the target element.
83 | 
84 | > `window.focusManager.unproxy(source,target)` - Removes a proxy.
85 | 
86 | ## Issues
87 | 
88 | If you would like to comment on the proposal, please [open an issue](https://github.com/awesomeeng/FocusTraversalAPI/issues).
89 | 
90 | ## License
91 | 
92 | The proposal and the polyfill library are available under the MIT License.
93 | 


--------------------------------------------------------------------------------
/src/DOMTraversal.js:
--------------------------------------------------------------------------------
  1 | (function (){
  2 | 	var first = function first(element,delveShadow) {
  3 | 		if (!element) throw new Error("Invalid element.");
  4 | 		return element.firstElementChild || delveShadow && element.shadowRoot && element.shadowRoot.firstElementChild || null;
  5 | 	};
  6 | 	var down = first;
  7 | 
  8 | 	var last = function last(element,delveShadow) {
  9 | 		if (!element) throw new Error("Invalid element.");
 10 | 		return delveShadow && element.shadowRoot && element.shadowRoot.lastElementChild || element.lastElementChild || null;
 11 | 	};
 12 | 	var downLast = last;
 13 | 
 14 | 	var up = function up(element,delveShadow) {
 15 | 		if (!element) throw new Error("Invalid element.");
 16 | 		return element.parentElement || delveShadow && element.parentNode instanceof DocumentFragment && element.parentNode.host || null;
 17 | 	};
 18 | 
 19 | 	var top = function top(element,delveShadow) {
 20 | 		if (!element) throw new Error("Invalid element.");
 21 | 		while(true) {
 22 | 			var e = up(element,delveShadow);
 23 | 			if (!e) break;
 24 | 			element = e;
 25 | 		}
 26 | 		return element;
 27 | 	};
 28 | 
 29 | 	var bottom = function bottom(element,delveShadow) {
 30 | 		if (!element) throw new Error("Invalid element.");
 31 | 		while (true) {
 32 | 			var e = down(element,delveShadow);
 33 | 			if (!e) break;
 34 | 			element = e;
 35 | 		}
 36 | 		return element;
 37 | 	};
 38 | 
 39 | 	var bottomLast = function bottomLast(element,delveShadow) {
 40 | 		if (!element) throw new Error("Invalid element.");
 41 | 		while (true) {
 42 | 			var e = downLast(element,delveShadow);
 43 | 			if (!e) break;
 44 | 			element = e;
 45 | 		}
 46 | 		return element;
 47 | 	};
 48 | 
 49 | 	var next = function next(element,delveShadow) {
 50 | 		if (!element) throw new Error("Invalid element.");
 51 | 
 52 | 		var c = element.firstElementChild || null;
 53 | 		if (c) return c;
 54 | 
 55 | 		var sc = delveShadow && element.shadowRoot && element.shadowRoot.firstElementChild || null;
 56 | 		if (sc) return element.shadowRoot.firstElementChild;
 57 | 
 58 | 		var sib = element.nextElementSibling || null;
 59 | 		if (sib) return sib;
 60 | 
 61 | 		var e = element;
 62 | 		while (true) {
 63 | 			e = up(e,delveShadow);
 64 | 			if (!e || e===element) return null;
 65 | 
 66 | 			sib = e.nextElementSibling;
 67 | 			if (sib) return sib;
 68 | 		}
 69 | 	};
 70 | 
 71 | 	var prev = function prev(element,delveShadow) {
 72 | 		if (!element) throw new Error("Invalid element.");
 73 | 
 74 | 		var sib = element.previousElementSibling;
 75 | 		if (sib) return bottomLast(sib,delveShadow);
 76 | 
 77 | 		var sc = delveShadow && !element.parentElement && element.parentNode && element.parentNode instanceof DocumentFragment && element.parentNode.host || null;
 78 | 		if (sc && sc.lastElementChild) return bottom(sc.lastElementChild,delveShadow);
 79 | 
 80 | 		var u = up(element,delveShadow);
 81 | 		return u;
 82 | 	};
 83 | 
 84 | 	var descendants = function descendants(element,delveShadow) {
 85 | 		if (!element) throw new Error("Invalid element.");
 86 | 
 87 | 		var desc = [];
 88 | 
 89 | 		var children = Array.prototype.slice.call(element.children);
 90 | 		children.forEach(function(c){
 91 | 			desc = desc.concat(c,descendants(c,delveShadow));
 92 | 		});
 93 | 
 94 | 		if (delveShadow && element.shadowRoot) {
 95 | 			var shadows = Array.prototype.slice.call(element.shadowRoot.children);
 96 | 			shadows.forEach(function(c){
 97 | 				desc = desc.concat(c,descendants(c,delveShadow));
 98 | 			});
 99 | 		}
100 | 
101 | 		return desc;
102 | 	};
103 | 
104 | 	var ancestors = function ancestors(element,delveShadow) {
105 | 		if (!element) throw new Error("Invalid element.");
106 | 
107 | 		var ansc = [];
108 | 		var e = element;
109 | 		while (e) {
110 | 			e = up(e,delveShadow);
111 | 			if (!e) break;
112 | 			ansc.push(e);
113 | 		}
114 | 		return ansc;
115 | 	};
116 | 
117 | 	var forwardList = function forwardList(element,delveShadow) {
118 | 		if (!element) throw new Error("Invalid element.");
119 | 		var elements = [];
120 | 
121 | 		var e = element;
122 | 		while (true) {
123 | 			if (!e) break;
124 | 			e = next(e,delveShadow);
125 | 			if (!e || e===element || !contains(element,e,delveShadow)) break;
126 | 			elements.push(e);
127 | 		}
128 | 		return elements;
129 | 	};
130 | 
131 | 	var backwardList = function backwardList(element,delveShadow) {
132 | 		if (!element) throw new Error("Invalid element.");
133 | 		return forwardList(element,delveShadow).reverse();
134 | 	};
135 | 
136 | 	var contains = function contains(container,element,delveShadow) {
137 | 		if (!container && !(container instanceof HTMLElement)) return false;
138 | 		if (!element && !(element instanceof HTMLElement)) return false;
139 | 
140 | 		if (!delveShadow) return container.contains(element);
141 | 
142 | 		var ancs = ancestors(element,true);
143 | 		return ancs.indexOf(container)>-1;
144 | 	};
145 | 
146 | 	var dom = {
147 | 		first: first,
148 | 		last: last,
149 | 		up: up,
150 | 		down: first,
151 | 		downLast: last,
152 | 		next: next,
153 | 		forward: next,
154 | 		prev: prev,
155 | 		previous: prev,
156 | 		backward: prev,
157 | 		top: top,
158 | 		bottom: bottom,
159 | 		bottomLast: bottomLast,
160 | 		descendants: descendants,
161 | 		ancestors: ancestors,
162 | 		forwardList: forwardList,
163 | 		backwardList: backwardList,
164 | 		contains: contains
165 | 	};
166 | 
167 | 	// can be used in node, mostly for testing
168 | 	// eslint-disable-next-line no-undef
169 | 	if (typeof module!=="undefined" && module && module.exports) {
170 | 		// eslint-disable-next-line no-undef
171 | 		module.exports = dom;
172 | 	}
173 | 
174 | 	// creates window.DOMTraversal for usage in browsers.
175 | 	if (typeof window!=="undefined" && window) {
176 | 		window.DOMTraversal = window.DOMTraversal || dom;
177 | 	}
178 | })();
179 | 


--------------------------------------------------------------------------------
/focus-traversal-api-polyfill.min.js:
--------------------------------------------------------------------------------
1 | !function(){var n=function(n,e){if(!n)throw new Error("Invalid element.");return n.firstElementChild||e&&n.shadowRoot&&n.shadowRoot.firstElementChild||null},e=n,t=function(n,e){if(!n)throw new Error("Invalid element.");return e&&n.shadowRoot&&n.shadowRoot.lastElementChild||n.lastElementChild||null},r=t,o=function(n,e){if(!n)throw new Error("Invalid element.");return n.parentElement||e&&n.parentNode instanceof DocumentFragment&&n.parentNode.host||null},i=function(n,t){if(!n)throw new Error("Invalid element.");for(;;){var r=e(n,t);if(!r)break;n=r}return n},u=function(n,e){if(!n)throw new Error("Invalid element.");for(;;){var t=r(n,e);if(!t)break;n=t}return n},a=function(n,e){if(!n)throw new Error("Invalid element.");var t=n.firstElementChild||null;if(t)return t;if(e&&n.shadowRoot&&n.shadowRoot.firstElementChild||null)return n.shadowRoot.firstElementChild;var r=n.nextElementSibling||null;if(r)return r;for(var i=n;;){if(!(i=o(i,e))||i===n)return null;if(r=i.nextElementSibling)return r}},l=function(n,e){if(!n)throw new Error("Invalid element.");var t=n.previousElementSibling;if(t)return u(t,e);var r=e&&!n.parentElement&&n.parentNode&&n.parentNode instanceof DocumentFragment&&n.parentNode.host||null;return r&&r.lastElementChild?i(r.lastElementChild,e):o(n,e)},f=function(n,e){if(!n)throw new Error("Invalid element.");for(var t=[],r=n;r&&(r=o(r,e));)t.push(r);return t},c=function(n,e){if(!n)throw new Error("Invalid element.");for(var t=[],r=n;r&&(r=a(r,e))&&r!==n&&s(n,r,e);)t.push(r);return t},s=function(n,e,t){return!!(n||n instanceof HTMLElement)&&(!!(e||e instanceof HTMLElement)&&(t?f(e,!0).indexOf(n)>-1:n.contains(e)))},d={first:n,last:t,up:o,down:n,downLast:t,next:a,forward:a,prev:l,previous:l,backward:l,top:function(n,e){if(!n)throw new Error("Invalid element.");for(;;){var t=o(n,e);if(!t)break;n=t}return n},bottom:i,bottomLast:u,descendants:function n(e,t){if(!e)throw new Error("Invalid element.");var r=[];Array.prototype.slice.call(e.children).forEach(function(e){r=r.concat(e,n(e,t))}),t&&e.shadowRoot&&Array.prototype.slice.call(e.shadowRoot.children).forEach(function(e){r=r.concat(e,n(e,t))});return r},ancestors:f,forwardList:c,backwardList:function(n,e){if(!n)throw new Error("Invalid element.");return c(n,e).reverse()},contains:s};"undefined"!=typeof module&&module&&module.exports&&(module.exports=d),"undefined"!=typeof window&&window&&(window.DOMTraversal=window.DOMTraversal||d)}(),function(){if("undefined"!=typeof window&&!window.focusManager){var n=window.DOMTraversal,e=function(n){if(!n)throw new Error("Missing array.");return n instanceof Array||(n=Array.prototype.slice.call(n)),n.reduce(function(n,e){return e instanceof Array?this.flatten(e).forEach(function(e){n.push(e)}):n.push(e),n},[])},t=[],r=50,o=null,i=document.activeElement||null,u=[],a=[],l=null,f=1e6,c=function(e){if(!e)return!1;if(!(e instanceof HTMLElement))return!1;for(var t=n.ancestors(e,!0).reverse(),r=0;r<t.length;r++){var o=t[r];if(o&&o instanceof HTMLElement){if(!0===(o.inert||!1))return!1;var i=window.getComputedStyle(o);if("none"===i.display)return!1;if("hidden"===i.visibility)return!1;var u=i.opacity;if((u=u&&parseInt(u)||1)<=0)return!1}}var a=e.getAttribute("tabindex")||null;if(null!==(a=a&&+a)&&a<0)return!1;if(null!==a&&a>=0)return!0;if(e.hasAttribute("disabled",null))return!1;var l=e.tagName;if("BUTTON"===l||"INPUT"===l||"SELECT"===l||"TEXTAREA"===l)return!0;if("A"===l&&(e.hasAttribute("href")||e.hasAttribute("xlink:href")))return!0;if("AUDIO"===l&&e.hasAttribute("controls"))return!0;if("VIDEO"===l&&e.hasAttribute("controls"))return!0;var f=e.getAttribute("contenteditable");return null!==f&&!0===f},s=function(n,e,t){n&&n instanceof Element&&("boolean"==typeof e&&(t=e,e=null),l&&clearTimeout(l),l=null,!0===t?n.focus(e||{}):l=setTimeout(function(){n.focus(e||{})},0))},d=function(e){e=e||document.body;var t=n.bottom(e,!0);if(t)return c(t)?t:(t=h(t),n.contains(e,t,!0)?t:null)},v=d,h=function(e){if(e||(e=i),!(e&&e instanceof Element))return null;for(;e&&(!(e=n.forward(e,!0))||!c(e)););for(var t=0;t<a.length;t++){var r=a[t];if(r.source===e){e=r.target;break}}return e},m=function e(t){if(t||(t=i),!(t&&t instanceof Element))return null;for(;t&&(!(t=n.backward(t,!0))||!c(t)););for(var r=0;r<a.length;r++){var o=a[r];if(o.source===t){t=e(o.source);break}}return t},w=function(n,e){a=a.filter(function(t){return t.source!==n||t.target!==e||(null!==t.sourceTabIndex?n.setAttribute("tabindex",t.sourceTabIndex):n.removeAttribute("tabindex"),!1)})};document.addEventListener("DOMContentLoaded",function(){document.addEventListener("focus",function(n){var e=n.target;if(n.composedPath){var o=n.composedPath();o.length>0&&(e=o[0])}i=e;var l=u[0]||null;l&&(l.last=e),t.unshift(e),r>-1&&(t=t.slice(0,r));for(var f=0;f<a.length;f++){var c=a[f];if(c.source===e)return void s(c.target)}},!0),document.addEventListener("blur",function(e){var t=e.target;if(e.composedPath){var r=e.composedPath();r.length>0&&(t=r[0])}var i=e.relatedTarget;if(i){var a=u[0]||null;if(a&&a.last){var l=n.ancestors(i,!0);a.containers.reduce(function(n,e){return n||l.indexOf(e)>-1},!1)||s(a.last)}}o=t},!0),document.addEventListener("keyup",function(n){if(n.shiftKey&&9===n.keyCode)for(var e=i,t=0;t<a.length;t++){var r=a[t];if(r.source===e||r.target===e)return s(m(r.source)),void n.preventDefault()}},!0)}),window.focusManager={isFocusable:c,focus:s,hasFocus:function(n){return!!(n&&n instanceof Element)&&i===n},list:function(e){return n.forwardList(e||document.body,!0).filter(function(n){return c(n)})},first:d,last:function(e){e=e||document.body;var t=n.bottomLast(e,!0);if(t)return c(t)?t:(t=m(t),n.contains(e,t,!0)?t:null)},parent:function(e){for(;e;)if(e=n.up(e,!0),c(e))return e;return null},child:v,forward:function(n){if(i){var e=h();e&&e!==i&&s(e,n||{})}},backward:function(n){if(i){var e=m();e&&e!==i&&s(e,n||{})}},next:h,previous:m,trap:function(){var n=Array.prototype.slice.call(arguments);if(!(n.length<1||(n=e(n)).some(function(n){return!(n instanceof HTMLElement)})||u.filter(function(e){return e.containers.every(function(e){return n.indexOf(e)>-1})}).length>0)){var t={containers:n,last:d(n[0]),blur:null};u.unshift(t),s(t.last)}},untrap:function(){if(!(u.length<1)){var n=Array.prototype.slice.call(arguments);if(!(n.length<1||(n=e(n)).some(function(n){return!(n instanceof HTMLElement)}))){var t=u.filter(function(e){return e.containers.every(function(e){return n.indexOf(e)>-1})}),r=t&&t.length>0&&u[0]&&u[0]===t[0];u=u.filter(function(e){return!e.containers.every(function(e){return n.indexOf(e)>-1})}),r&&u[0]&&s(u[0].last)}}},order:function(){var n=null;e(arguments).forEach(function(e){if("number"!=typeof e){if(e instanceof HTMLElement){var t=f++;null!==n&&(t=n++),e.setAttribute("tabindex",""+t)}}else n=e})},proxy:function(n,e){if(n&&n instanceof HTMLElement&&e&&e instanceof HTMLElement&&c(e)){w(n,e);var t=n.getAttribute("tabindex")||null;(null===(t=t&&parseInt(t)||null)||t<0)&&n.setAttribute("tabindex",0),a.push({source:n,target:e,sourceTabIndex:t}),i===n&&s(e)}},unproxy:w},Object.defineProperty(window.focusManager,"currentlyFocused",{get:function(){return i}}),Object.defineProperty(window.focusManager,"previouslyFocused",{get:function(){return o||null}}),Object.defineProperty(window.focusManager,"history",{get:function(){return[].concat(t)}}),Object.defineProperty(window.focusManager,"historyLimit",{get:function(){return r},set:function(n){n=parseInt(n),isNaN(n)||n<-1||(r=n)>-1&&(t=t.slice(0,r))}})}}();
2 | 


--------------------------------------------------------------------------------
/TheCaseForFocus.md:
--------------------------------------------------------------------------------
 1 | # The Case for a New Focus System
 2 | 
 3 | Twenty years ago I wrote my first Web Application. Essentially a message board system it had no semblance to a modern web application, of course, but it contained many of the features we see on modern applications even now. Users could register, login, read messages, post messages, reply, etc. It was written in ColdFusion 1.5 and everything was backed to a Microsoft Access Database; ancient technology by any modern standards.
 4 | 
 5 | The reason for this personal memory reflection is to illustrate a specific problem I had back then, a specific problem that we as web developers still face today: Focus.
 6 | 
 7 | See, in my nascent Web Application there was a login form: standard username and password and submit button thing we have today. And I wanted the user to be able to type their username, press ENTER to move to the next field, type their password, and press ENTER to submit. This field advancement behavior mimicked they way the logged into their network accounts at the time. This meant turning to JavaScript: a language and concept just in its infancy.
 8 | 
 9 | The need was to notice when someone pressed the ENTER key while in the currently focused field. When that occurred, I wanted to advance the focus to next field. Simple, right?
10 | 
11 | Move the clock forward some twenty years. I am building a web application for my new company and, of course, it has a login form with a username, password, and submit button. And, of course, I want to advance the focus when someone presses ENTER. It should come as no surprise but twenty years later and I have the exact same problem to solve. Instead, the surprising bit is that twenty years later, it still has the same solution:
12 | 
13 | ```JavaScript
14 | var usernameField = form.querySelector("input[type=text]");
15 | var passwordField = form.querySelector("input[type=password]");
16 | usernameField.addEventListener("keyup",function(event){
17 | 	if (event.code!=="Enter") return;
18 | 	passwordField.focus();
19 | });
20 | ```
21 | 
22 | ## The Current Focus API
23 | 
24 | The history of our current focus system is pretty simple...
25 | 
26 | In January of 1998 we get the [first formal specification of focus](https://www.w3.org/TR/REC-DOM-Level-1/level-one-html.html#method-focus) in the Document Object Model (DOM) Level 1 Specification.
27 | 
28 |  * `element.focus()` and `element.blur()` work almost identically the same as they did twenty years ago.  `element.focus()` will request the focus be given to a specific element.  `element.blur()` will move the focus upwards in the DOM to its parent focusable container.
29 | 
30 | Later we get focus events...
31 | 
32 |  * `focus` and  `blur` events let one track where the current focus is and respond to changes in the focus. `focusin` and `focusout` are defined around this time as well, but we do not formally get them until much later.
33 | 
34 | Still later we get a few more small focus additions.
35 | 
36 |  * `document.hasFocus()` will indicate if a given document has focus either itself or as one of its descendants.
37 | 
38 |  * `document.activeElement` will return the current element of the document that holds the focus, if any.
39 | 
40 | Together these represent the state of the current focus system we have today. It's adequate, it gets the job done, but it could be, **it should be** so much more.
41 | 
42 | ## The Problem with Focus Today
43 | 
44 | There are two very specific problems with our current focus system...
45 | 
46 | 1). **Determining if an element can receive the focus is extremely complicated.**  There are well defined rules in the [WHATWG HTML Specification (section 6.4)](https://html.spec.whatwg.org/multipage/interaction.html#focus) but specifications can be hard to read and getting this right has been a problem for many who have tried.  INPUT tags, Anchor tags, the `tabindex` attrbitues, ARIA attributes, etc., they all contribute to whether or not an element can receive focus; not to mention if an element SHOULD recieve focus.
47 | 
48 | 2). **There is no way to move the focus forward or backward without knowing what element needs to receive the focus.** This is especially becoming more problematic in the age of Web Components. Say, for example, I wanted to write a Web Component for a username field that would advance the focus to the next focusable element when ENTER is pressed.  From the components perspective it knows nothing about what is outside of it, what element receives the focus next. Advancing the focus is entirely impossible without external knowledge.
49 | 
50 | Both of these problems make working with focus harder than it needs to be.  A modern web developer should not have to go to difficult lengths to do simple, common things. We can do it better.
51 | 
52 | ## Solving Modern Focus
53 | 
54 | To address focus for modern web development, we need to answer both of these concerns.  We need a means to determine what is focusable and a means to advance to, and fallback from, the actively focused element. Answering these two points is paramount.  If we can add in some other "nice to haves", so much the better.
55 | 
56 | First and foremost, we need a call to determine if an element is focusable or not.  A call such as `element.isFocusable()` whould work ideally here.  It should respond with a boolean true or false and take into account all of the various ins and outs of whether something can be focused and absolve the developers from having to interpret the specification themselves.
57 | 
58 | Second, a means to move the focus forward or backward from some given element without knowing what is before or after it.  This can take a form such as `focusManager.forward()` or `focusManager.backward()`. Additionally, while we are at it, a means to identify what is the next or previous focus of any given element should be easy to determine.  Something like `focusManager.next(element)` or `focusManager.previous(element)` that will return the next or previous element that could receive the focus.
59 | 
60 | A handful of other convience methods are also extremely easy to do once we have `element.isFocusable()`. A means to get all of the focusable elements of the container, for example, with `focusManager.list(element)`.  Or even more simple would be to have a way to find what was last focused prior to the current focus such as `focusManager.previouslyFocused` or a history of focus changes such as `focusManager.history`.
61 | 
62 | All of these new focus requirements are geared at making focus easier to use and easier to understand.  This in turn lends itself to creating more consistency for the users, which means easier and more understandable user interfaces and happier customers for everyone.
63 | 
64 | With these new APIs, moving focus goes from the code we showed you above to
65 | 
66 | ```javascript
67 | form.querySelector("input[type=text]").addEventListener("keyup",function(event){
68 | 	if (event.code!=="Enter") return;
69 | 	focusManager.forward();
70 | });
71 | ```
72 | 
73 | It's not a huge reduction in lines of code, but it is vastly superior in complexity of understanding. And that should be the goal of any new system.
74 | 
75 | ## Making It Happen
76 | 
77 | So, how do we make focus better, how do we make the things we discussed here a reality for all?
78 | 
79 | To address the problems of focus once and for all requires a change to the HTML specification that is managed by the W3C. Unless you are one of the big three browser creators, the process to enact change within the standards is very difficult. Fortunately, the W3C knows that this can be difficult and it created the Web Incubator Community Group or WICG. This is an online community dedicated to discussing and promoting new ideas for the W3C to consider. The WICG was created specifically for "everyday citizens" to propose and discuss changes to the W3C standards.
80 | 
81 | To that end the FocusTraversal API, which encapsualtes all of the focus related features offered in this article, was [proposed to the WICG](https://discourse.wicg.io/t/proposal-focus-traversal-api/3427) on March 13, 2019.
82 | 
83 | But the WICG is a very tiny microcosm and not a lot of people know it exists, even within the W3C standards body.  The WICG is the starting point for any [proposal](https://discourse.wicg.io/t/proposal-focus-traversal-api/3427), but to really enact change you need community support.  And this is where you can help: the FocusTraversal API proposal will never be realized without a lot more support.  It needs further discussion in WICG; it needs outside promotion on twitter, reddit, and the like; and it needs participation and issues on Github.
84 | 
85 | We have gotten the ball rolling. We have written the [PROPOSAL](https://discourse.wicg.io/t/proposal-focus-traversal-api/3427) and a more detailed [EXPLAINER](https://github.com/awesomeeng/FocusTraversalAPI/blob/master/EXPLAINER.md). We have written a [POLYFILL](https://github.com/awesomeeng/FocusTraversalAPI) to demonstrate the ideas. Yet writing these thing is the easy part; spreading the word is the challenge.  If you want to help, and we are begging for help here, we need more engagement. We need discussion about the [proposal](https://discourse.wicg.io/t/proposal-focus-traversal-api/3427) on the WICG Discourse board; we need [participation in the Github](https://github.com/awesomeeng/FocusTraversalAPI) with issues and pulls and comments; and we need help spreading the word on twitter and reddit and blogs and the like.
86 | 
87 | So, if you are willing to help, and we hope you are, please get involved, please spread the word, and please help us make focus easier to use for everyone.
88 | 
89 | ## More Information
90 | 
91 |  - PROPOSAL: [https://discourse.wicg.io/t/proposal-focus-traversal-api/3427](https://discourse.wicg.io/t/proposal-focus-traversal-api/3427)
92 | 
93 |  - EXPLAINER: [https://github.com/awesomeeng/FocusTraversalAPI/blob/master/EXPLAINER.md](https://github.com/awesomeeng/FocusTraversalAPI/blob/master/EXPLAINER.md)
94 | 
95 |  - POLYFILL: [https://github.com/awesomeeng/FocusTraversalAPI](https://github.com/awesomeeng/FocusTraversalAPI)
96 | 
97 |  - GITHUB: [https://github.com/awesomeeng/FocusTraversalAPI](https://github.com/awesomeeng/FocusTraversalAPI)
98 | 


--------------------------------------------------------------------------------
/test/DOMTraversalTest.js:
--------------------------------------------------------------------------------
  1 | // (c) 2018, The Awesome Engineering Company, https://awesomeneg.com
  2 | 
  3 | /*
  4 | 	Tests for .......
  5 |  */
  6 | 
  7 | "use strict";
  8 | 
  9 | const assert = require("assert");
 10 | const DT = require("../src/DOMTraversal");
 11 | const {JSDOM} = require("jsdom");
 12 | 
 13 | let tree = new JSDOM(`<!DOCTYPE html>
 14 | <html class="html">
 15 | 	<head class="head">
 16 | 		<meta class="meta"></meta>
 17 | 		<script class="script"></script>
 18 | 	</head>
 19 | 	<body class="body">
 20 | 		<div class="a">
 21 | 			<div class="aa">
 22 | 				<div class="aaa">
 23 | 				</div>
 24 | 			</div>
 25 | 			<div class="ab">
 26 | 			</div>
 27 | 		</div>
 28 | 		<div class="b">
 29 | 		</div>
 30 | 		<div class="c">
 31 | 			<div class="ca">
 32 | 			</div>
 33 | 			<div class="cb">
 34 | 			</div>
 35 | 			<div class="cc">
 36 | 			</div>
 37 | 		</div>
 38 | 		<div class="d">
 39 | 			<div class="da">
 40 | 				<div class="daa">
 41 | 				</div>
 42 | 				<div class="dab">
 43 | 					<div class="daba">
 44 | 					</div>
 45 | 				</div>
 46 | 				<div class="dac">
 47 | 				</div>
 48 | 			</div>
 49 | 		</div>
 50 | 	</body>
 51 | </html>
 52 | `);
 53 | let window = tree.window;
 54 | let document = window.document;
 55 | let html = document.body.parentElement;
 56 | let body = document.body;
 57 | let head = document.head;
 58 | 
 59 | let nodes = {
 60 | 	a: body.querySelector(".a"),
 61 | 	aa: body.querySelector(".aa"),
 62 | 	aaa: body.querySelector(".aaa"),
 63 | 	ab: body.querySelector(".ab"),
 64 | 	b: body.querySelector(".b"),
 65 | 	c: body.querySelector(".c"),
 66 | 	ca: body.querySelector(".ca"),
 67 | 	cb: body.querySelector(".cb"),
 68 | 	cc: body.querySelector(".cc"),
 69 | 	d: body.querySelector(".d"),
 70 | 	da: body.querySelector(".da"),
 71 | 	daa: body.querySelector(".daa"),
 72 | 	dab: body.querySelector(".dab"),
 73 | 	daba: body.querySelector(".daba"),
 74 | 	dac: body.querySelector(".dac")
 75 | };
 76 | 
 77 | describe("DOMTraversal",function(){
 78 | 	it("available",function(){
 79 | 		assert(DT);
 80 | 	});
 81 | 
 82 | 	it("#down",function(){
 83 | 		assert.equal(DT.down(body),nodes.a);
 84 | 		assert.equal(DT.down(nodes.a),nodes.aa);
 85 | 		assert.equal(DT.down(nodes.aa),nodes.aaa);
 86 | 		assert.equal(DT.down(nodes.aaa),null);
 87 | 	});
 88 | 
 89 | 	it("#downLast",function(){
 90 | 		assert.equal(DT.downLast(body),nodes.d);
 91 | 		assert.equal(DT.downLast(nodes.a),nodes.ab);
 92 | 		assert.equal(DT.downLast(nodes.aa),nodes.aaa);
 93 | 		assert.equal(DT.downLast(nodes.aaa),null);
 94 | 		assert.equal(DT.downLast(nodes.c),nodes.cc);
 95 | 	});
 96 | 
 97 | 	it("#up",function(){
 98 | 		assert.equal(DT.up(nodes.a),body);
 99 | 		assert.equal(DT.up(nodes.aa),nodes.a);
100 | 		assert.equal(DT.up(nodes.aaa),nodes.aa);
101 | 	});
102 | 
103 | 	it("#first",function(){
104 | 		assert.equal(DT.first(body),nodes.a);
105 | 		assert.equal(DT.first(nodes.a),nodes.aa);
106 | 		assert.equal(DT.first(nodes.b),null);
107 | 		assert.equal(DT.first(nodes.c),nodes.ca);
108 | 		assert.equal(DT.first(nodes.d),nodes.da);
109 | 	});
110 | 
111 | 	it("#last",function(){
112 | 		assert.equal(DT.last(body),nodes.d);
113 | 		assert.equal(DT.last(nodes.a),nodes.ab);
114 | 		assert.equal(DT.last(nodes.b),null);
115 | 		assert.equal(DT.last(nodes.c),nodes.cc);
116 | 		assert.equal(DT.last(nodes.d),nodes.da);
117 | 	});
118 | 
119 | 	it("#top",function(){
120 | 		assert.equal(DT.top(body),html);
121 | 		assert.equal(DT.top(nodes.aaa),html);
122 | 		assert.equal(DT.top(nodes.aa),html);
123 | 		assert.equal(DT.top(nodes.cb),html);
124 | 		assert.equal(DT.top(nodes.dac),html);
125 | 	});
126 | 
127 | 	it("#bottom",function(){
128 | 		assert.equal(DT.bottom(body),nodes.aaa);
129 | 		assert.equal(DT.bottom(nodes.a),nodes.aaa);
130 | 		assert.equal(DT.bottom(nodes.b),nodes.b);
131 | 		assert.equal(DT.bottom(nodes.c),nodes.ca);
132 | 		assert.equal(DT.bottom(nodes.d),nodes.daa);
133 | 	});
134 | 
135 | 	it("#bottomLast",function(){
136 | 		assert.equal(DT.bottomLast(body),nodes.dac);
137 | 		assert.equal(DT.bottomLast(nodes.a),nodes.ab);
138 | 		assert.equal(DT.bottomLast(nodes.b),nodes.b);
139 | 		assert.equal(DT.bottomLast(nodes.c),nodes.cc);
140 | 		assert.equal(DT.bottomLast(nodes.d),nodes.dac);
141 | 	});
142 | 
143 | 	it("#next",function(){
144 | 		assert.equal(DT.next(body),nodes.a);
145 | 		assert.equal(DT.next(nodes.a),nodes.aa);
146 | 		assert.equal(DT.next(nodes.aa),nodes.aaa);
147 | 		assert.equal(DT.next(nodes.aaa),nodes.ab);
148 | 		assert.equal(DT.next(nodes.ab),nodes.b);
149 | 		assert.equal(DT.next(nodes.b),nodes.c);
150 | 		assert.equal(DT.next(nodes.c),nodes.ca);
151 | 		assert.equal(DT.next(nodes.ca),nodes.cb);
152 | 		assert.equal(DT.next(nodes.cb),nodes.cc);
153 | 		assert.equal(DT.next(nodes.cc),nodes.d);
154 | 		assert.equal(DT.next(nodes.d),nodes.da);
155 | 		assert.equal(DT.next(nodes.da),nodes.daa);
156 | 		assert.equal(DT.next(nodes.daa),nodes.dab);
157 | 		assert.equal(DT.next(nodes.dab),nodes.daba);
158 | 		assert.equal(DT.next(nodes.daba),nodes.dac);
159 | 		assert.equal(DT.next(nodes.dac),null);
160 | 	});
161 | 
162 | 	it("#forward",function(){
163 | 		assert.equal(DT.forward(body),nodes.a);
164 | 		assert.equal(DT.forward(nodes.a),nodes.aa);
165 | 		assert.equal(DT.forward(nodes.aa),nodes.aaa);
166 | 		assert.equal(DT.forward(nodes.aaa),nodes.ab);
167 | 		assert.equal(DT.forward(nodes.ab),nodes.b);
168 | 		assert.equal(DT.forward(nodes.b),nodes.c);
169 | 		assert.equal(DT.forward(nodes.c),nodes.ca);
170 | 		assert.equal(DT.forward(nodes.ca),nodes.cb);
171 | 		assert.equal(DT.forward(nodes.cb),nodes.cc);
172 | 		assert.equal(DT.forward(nodes.cc),nodes.d);
173 | 		assert.equal(DT.forward(nodes.d),nodes.da);
174 | 		assert.equal(DT.forward(nodes.da),nodes.daa);
175 | 		assert.equal(DT.forward(nodes.daa),nodes.dab);
176 | 		assert.equal(DT.forward(nodes.dab),nodes.daba);
177 | 		assert.equal(DT.forward(nodes.daba),nodes.dac);
178 | 		assert.equal(DT.forward(nodes.dac),null);
179 | 	});
180 | 
181 | 	it("#previous",function(){
182 | 		assert.equal(DT.previous(nodes.dac),nodes.daba);
183 | 		assert.equal(DT.previous(nodes.daba),nodes.dab);
184 | 		assert.equal(DT.previous(nodes.dab),nodes.daa);
185 | 		assert.equal(DT.previous(nodes.daa),nodes.da);
186 | 		assert.equal(DT.previous(nodes.da),nodes.d);
187 | 		assert.equal(DT.previous(nodes.d),nodes.cc);
188 | 		assert.equal(DT.previous(nodes.cc),nodes.cb);
189 | 		assert.equal(DT.previous(nodes.cb),nodes.ca);
190 | 		assert.equal(DT.previous(nodes.ca),nodes.c);
191 | 		assert.equal(DT.previous(nodes.c),nodes.b);
192 | 		assert.equal(DT.previous(nodes.b),nodes.ab);
193 | 		assert.equal(DT.previous(nodes.ab),nodes.aaa);
194 | 		assert.equal(DT.previous(nodes.aaa),nodes.aa);
195 | 		assert.equal(DT.previous(nodes.aa),nodes.a);
196 | 		assert.equal(DT.previous(nodes.a),body);
197 | 	});
198 | 
199 | 	it("#backward",function(){
200 | 		assert.equal(DT.backward(nodes.dac),nodes.daba);
201 | 		assert.equal(DT.backward(nodes.daba),nodes.dab);
202 | 		assert.equal(DT.backward(nodes.dab),nodes.daa);
203 | 		assert.equal(DT.backward(nodes.daa),nodes.da);
204 | 		assert.equal(DT.backward(nodes.da),nodes.d);
205 | 		assert.equal(DT.backward(nodes.d),nodes.cc);
206 | 		assert.equal(DT.backward(nodes.cc),nodes.cb);
207 | 		assert.equal(DT.backward(nodes.cb),nodes.ca);
208 | 		assert.equal(DT.backward(nodes.ca),nodes.c);
209 | 		assert.equal(DT.backward(nodes.c),nodes.b);
210 | 		assert.equal(DT.backward(nodes.b),nodes.ab);
211 | 		assert.equal(DT.backward(nodes.ab),nodes.aaa);
212 | 		assert.equal(DT.backward(nodes.aaa),nodes.aa);
213 | 		assert.equal(DT.backward(nodes.aa),nodes.a);
214 | 		assert.equal(DT.backward(nodes.a),body);
215 | 	});
216 | 
217 | 	it("#descendants",function(){
218 | 		assert.deepStrictEqual(DT.descendants(body),[nodes.a, nodes.aa, nodes.aaa, nodes.ab, nodes.b, nodes.c, nodes.ca, nodes.cb, nodes.cc, nodes.d, nodes.da, nodes.daa, nodes.dab, nodes.daba, nodes.dac]);
219 | 		assert.deepStrictEqual(DT.descendants(nodes.a),[nodes.aa, nodes.aaa, nodes.ab]);
220 | 	});
221 | 
222 | 	it("#ancestors",function(){
223 | 		assert.deepStrictEqual(DT.ancestors(body),[html]);
224 | 		assert.deepStrictEqual(DT.ancestors(nodes.a),[body,html]);
225 | 		assert.deepStrictEqual(DT.ancestors(nodes.aa),[nodes.a,body,html]);
226 | 		assert.deepStrictEqual(DT.ancestors(nodes.aaa),[nodes.aa,nodes.a,body,html]);
227 | 		assert.deepStrictEqual(DT.ancestors(nodes.b),[body,html]);
228 | 		assert.deepStrictEqual(DT.ancestors(nodes.c),[body,html]);
229 | 		assert.deepStrictEqual(DT.ancestors(nodes.ca),[nodes.c,body,html]);
230 | 		assert.deepStrictEqual(DT.ancestors(nodes.cb),[nodes.c,body,html]);
231 | 		assert.deepStrictEqual(DT.ancestors(nodes.cc),[nodes.c,body,html]);
232 | 		assert.deepStrictEqual(DT.ancestors(nodes.d),[body,html]);
233 | 		assert.deepStrictEqual(DT.ancestors(nodes.da),[nodes.d,body,html]);
234 | 		assert.deepStrictEqual(DT.ancestors(nodes.daa),[nodes.da,nodes.d,body,html]);
235 | 		assert.deepStrictEqual(DT.ancestors(nodes.dab),[nodes.da,nodes.d,body,html]);
236 | 		assert.deepStrictEqual(DT.ancestors(nodes.daba),[nodes.dab,nodes.da,nodes.d,body,html]);
237 | 		assert.deepStrictEqual(DT.ancestors(nodes.dac),[nodes.da,nodes.d,body,html]);
238 | 	});
239 | 
240 | 	it("#forwardList",function(){
241 | 		assert.deepStrictEqual(DT.forwardList(body),[nodes.a,nodes.aa,nodes.aaa,nodes.ab,nodes.b,nodes.c,nodes.ca,nodes.cb,nodes.cc,nodes.d,nodes.da,nodes.daa,nodes.dab,nodes.daba,nodes.dac]);
242 | 		assert.deepStrictEqual(DT.forwardList(nodes.a),[nodes.aa,nodes.aaa,nodes.ab]);
243 | 		assert.deepStrictEqual(DT.forwardList(nodes.c),[nodes.ca,nodes.cb,nodes.cc]);
244 | 		assert.deepStrictEqual(DT.forwardList(nodes.d),[nodes.da,nodes.daa,nodes.dab,nodes.daba,nodes.dac]);
245 | 	});
246 | 
247 | 	it("#backwardList",function(){
248 | 		assert.deepStrictEqual(DT.backwardList(body),[nodes.dac,nodes.daba,nodes.dab,nodes.daa,nodes.da,nodes.d,nodes.cc,nodes.cb,nodes.ca,nodes.c,nodes.b,nodes.ab,nodes.aaa,nodes.aa,nodes.a]);
249 | 		assert.deepStrictEqual(DT.backwardList(nodes.a),[nodes.ab,nodes.aaa,nodes.aa]);
250 | 		assert.deepStrictEqual(DT.backwardList(nodes.c),[nodes.cc,nodes.cb,nodes.ca]);
251 | 		assert.deepStrictEqual(DT.backwardList(nodes.d),[nodes.dac,nodes.daba,nodes.dab,nodes.daa,nodes.da]);
252 | 	});
253 | 
254 | 
255 | 
256 | 
257 | });
258 | 


--------------------------------------------------------------------------------
/EXPLAINER.md:
--------------------------------------------------------------------------------
  1 | # Focus Traversal API
  2 | 
  3 | This is a proposed feature that would allow an author to better understand and manipulate the Focus system within a web page.  This includes support for computing the next and previous Focus targets for any given element, moving the focus forward or backward programatically from an element without knowing the next focus target, and other focus related features.
  4 | 
  5 | ## The Problem
  6 | 
  7 | The current system for programmatically manipulating focus within a web page leaves a lot to be desired. A single element can request the focus with the `focus()` method but that is the extent of the programatic focus navigation options.  Advancing the focus to the next focusable element or the previous focusable element involves a complex dance of DOM traversal and guess work as to what elements can receive focus or not.  Most solutions to manipulating focus are complicated; the very simple need to manipulate focus in a meaningful and accessable manner is significantly lacking.
  8 | 
  9 | #### Focusable
 10 | 
 11 | A big part of the problem is how one determines if an element is "focusable" or not and can receive focus.  There are very complex rules associated with this process as outlined in section 5.4.2 of the [W3C HTML Standard (as of 5.3 Working Draft, 18 October 2018)](https://www.w3.org/TR/2018/WD-html53-20181018/editing.html#data-model). These rules are fairly stable, but could change and expecting userland modules to keep in sync or even be in sync currently is unrealistic.
 12 | 
 13 | #### Moving Focus Programatically
 14 | 
 15 | In order to move focus from any given element to the next (or prior) focusable element is complicated. One would need to walk the DOM in a forward manner (down to lowest leaf of next sibling, then next sibling, then parent, etc). For each element, one would need to apply the rules for what is focusable.  If the element is focusable, move the focus there.  If not, move to the next element.
 16 | 
 17 | This is not an easy process for users.  Many userland modules and frameworks attempt to solve this problem, but as stated above there is a an unrealistic expectation of these modules to stay in concert with the focusable rules.
 18 | 
 19 | ## The Focus Traversal API
 20 | 
 21 | This proposal introduces the concepts of a Focus Traversal API to solve these problems. This API exists as an additional set of behaviours over and above what can be done with the existing focus system.
 22 | 
 23 | ### The `window.focusManager` Object
 24 | 
 25 | This proposal suggests the creating of a top level `window` property called `focusManager` which will be used to expose a series of properties and methods for working with Focus traversal.
 26 | 
 27 | #### Focusable
 28 | 
 29 | To address the complexity with determining if an element is focusable or not it is porposed to create `focusManager.isFocusable(element)` which will return true if the given element is able to receive the focus according to the Focus rules laid out in section 5.4.2 of the [W3C HTML Standard (as of 5.3 Working Draft, 18 October 2018)](https://www.w3.org/TR/2018/WD-html53-20181018/editing.html#data-model).
 30 | 
 31 | #### Next/Previous Focus
 32 | 
 33 | Moving the focus forward or backward is a key operation for developers and the Focus Traversal API seeks to ease this process greatly with the `focusManager.next(element)` and the `focusManager.previous(element)` methods.  These functions will return the next (or previous) element that meets the `focusManager.isFocusable()` condition, or null if there are no next or previous elements that meet the requirement.
 34 | 
 35 | #### Forward/Backward Focus Traversal
 36 | 
 37 | A method to allow users to programatically move the focus forward or backward without having to manually compute the next or previous focus is highly desireable. `focusManager.forward()` takes the currently focused element and computes the next element that meets the `focusManager.isFocusable()` condition, and advances the focus to that element using `element.focus()`. `focusManager.backward()` is similar but it computes the pervious element that meets the `focusManager.isFocusable()` condition and moves the focus to that element using `element.focus()`.
 38 | 
 39 | #### Other Features
 40 | 
 41 | As part of this proposal some additional conveinience methods and properties are offered in an attempt to centralize and organize the focus system.
 42 | 
 43 | `window.focusManager.currentlyFocused` - Contains the element currently holding the focus, if any.
 44 | 
 45 | `window.focusManager.previouslyFocused` - Contains the element that held the focus prior to the current focus, if any.
 46 | 
 47 | `window.focusManager.history` - An array of the last n historical focus holders. It is recommended this be capped at some number like 50 or 100 to prevent unnecessary memory leakage.
 48 | 
 49 | `window.focusManager.hasFocus(element)` - Returns true if the given element currently has the focus.  Functionally equivelent to `window.focusManager.currentlyFocused === element`.
 50 | 
 51 | `window.focusManager.focus(element,focusOption)` - Focus on the given element. Functionally the same as `element.focus()`. Returns void.
 52 | 
 53 | `window.focusManager.list(element)` - Returns an array of all focusable elements in the order that focus traversal would occur.
 54 | 
 55 | `window.focusManager.order(element,element,element,etc)` - Programatically set the traversal order of one or more elements. Given an array of elements (or multiple arguments) order them in the order they are given.
 56 | 
 57 | `window.focusManager.trap(element)` - Trap focus within a given element, such that any focus event outside of the element's descendants will refocus the last focused element within the element's descendants. Traps calls stack, such that the latest trap always wins, but removing a trap will set th enext prior trap running.
 58 | 
 59 | `window.focusManager.untrap(element)` - Removes a trap.
 60 | 
 61 | `window.focusManager.proxy(source,target)` - When the given source element receives the focus, forward that focus immediately to the target element.
 62 | 
 63 | `window.focusManager.unproxy(source,target)` - Removes a proxy.
 64 | 
 65 | ### Special Considerations
 66 | 
 67 | Some special cases occur to which this specification must be mindful:
 68 | 
 69 |  - ShadowDOM: It is proposed that the Focus Management API also delve into ShadowDOM elements when computing the next or previous focus. If an element has an attached ShadowDOM, it must be traversed in accordance with its contents and any `<slot>` elements.
 70 | 
 71 |  - In especially large DOM trees computing the next focus, previous focus, or the `list()` list could be significantly slow.  It is recommended that these functions be asyncrounous and return a Promise instead of syncronously blocking.
 72 | 
 73 | ## Benefits
 74 | 
 75 | The benefits of adopting this proposal include easing developer efforts in regard to Focus, more consistent behavior between web pages and applications, and increasing performance.  No longer would developers be forced to rely on third party focus libraries nor forced to compute what is or is not focused manually thus reducing their exposure to errors and inconsistency.
 76 | 
 77 | ## Concerns
 78 | 
 79 | Largely, this proposal should not impact any existing systems as it is an addition to instead of a replacement or removal.  Some consideration should be made to extract out the rule system for determining the focus-ability of an element into a common space if not already done so by implementors.
 80 | 
 81 | Also, this proposal is currently unsure about how this would interact with an `<iframe>` or anything that contains its own document structure.
 82 | 
 83 | ## Proposed API
 84 | 
 85 | > `window.focusManager.currentlyFocused` - Contains the element currently holding the focus, if any.
 86 | 
 87 | > `window.focusManager.previouslyFocused` - Contains the element that held the focus prior to the current focus, if any.
 88 | 
 89 | > `window.focusManager.history` - An array of the last n historical focus holders.
 90 | 
 91 | > `window.focusManager.historyLimit` - A number indicating how may focus history events should be retained. Defaults to 50.
 92 | 
 93 | > `window.focusManager.isFocusable(element)` - Returns true if the given element can receive focus.
 94 | 
 95 | > `window.focusManager.hasFocusable(element)` - Returns true if the given element currently has the focus.
 96 | 
 97 | > `window.focusManager.focus(element,focusOption)` - Focus on the given element. Functionally the same as `element.focus()`. Returns void.
 98 | 
 99 | > `window.focusManager.forward(focusOption)` - Move the focus to the next focusable element.  Returns void.
100 | 
101 | > `window.focusManager.backward(focusOption)` - Move the focus to the previous focusable element.  Returns void.
102 | 
103 | > `window.focusManager.next(element)` - Returns the element that would receive the focus if `window.focusManager.forward()` was called when the given element has the focus.  If no element is given, the currently focused element is used.
104 | 
105 | > `window.focusManager.previous(element)` - Returns the element that would receive the focus if `window.focusManager.backward()` was called when the given element has the focus.  If no element is given, the currently focused element is used.
106 | 
107 | > `window.focusManager.list(container)` - Returns an array of all focusable elements in the order that focus traversal would occur. If container is provided and a valid HTMLElement, this would limit the results to only the children of the given container. If no container is provided, the current document is used as the container.
108 | 
109 | > `window.focusManager.first(container)` - Returns the first element that would receive focus for the given container, or the current document if no container is provided.
110 | 
111 | > `window.focusManager.last(container)` - Returns the first element that would receive focus for the given container, or the current document if no container is provided.
112 | 
113 | `window.focusManager.order(element,element,element,etc)` - Programatically set the traversal order of one or more elements. Given an array of elements (or multiple arguments) order them in the order they are given.
114 | 
115 | `window.focusManager.trap(element)` - Trap focus within a given element, such that any focus event outside of the element's descendants will refocus the last focused element within the element's descendants. Traps calls stack, such that the latest trap always wins, but removing a trap will set th enext prior trap running.
116 | 
117 | `window.focusManager.untrap(element)` - Removes a trap.
118 | 
119 | `window.focusManager.proxy(source,target)` - When the given source element receives the focus, forward that focus immediately to the target element.
120 | 
121 | `window.focusManager.unproxy(source,target)` - Removes a proxy.
122 | 
123 | ## Status
124 | 
125 | This proposal is currently in the proposal phase and collecting suggestions and feedback.  To date no comments have been surfaced against the idea and community interest is positive.
126 | 
127 | ## Polyfill
128 | 
129 | An example implementation of the above as well as this document can be found at [https://github.com/awesomeeng/FocusTraversalAPI](https://github.com/awesomeeng/FocusTraversalAPI).
130 | 
131 | ## Illustrative User Issues
132 | 
133 |  - https://stackoverflow.com/questions/7208161/focus-next-element-in-tab-index
134 |  - https://stackoverflow.com/questions/3639908/retrieving-previously-focused-element
135 | 
136 | ## Similar Works
137 | 
138 |  - https://github.com/davidtheclark/tabbable - A very popular library for getting a list of all the elements in a element that can receive the focus.
139 | 
140 | ## Revision History
141 | 
142 |  - v1 - April 24, 2019 - Initial creation of Explainer.
143 |  - v2 - October 28, 2019 - Added order(), trap(), untrap(), proxy(), unproxy(). Renamed orderedElements() to list().
144 | 


--------------------------------------------------------------------------------
/src/focus-traversal-api-polyfill.js:
--------------------------------------------------------------------------------
  1 | // requires DOMTraversal.
  2 | 
  3 | (function (){
  4 | 	if (typeof window==="undefined" || window.focusManager) return;
  5 | 
  6 | 	var DT = window.DOMTraversal;
  7 | 
  8 | 	// array helpers
  9 | 	var flatten = function flatten(array) {
 10 | 		if (!array) throw new Error("Missing array.");
 11 | 		if (!(array instanceof Array)) array = Array.prototype.slice.call(array);
 12 | 
 13 | 		return array.reduce(function(array,x) {
 14 | 			if (x instanceof Array) {
 15 | 				this.flatten(x).forEach(function(x) {
 16 | 					array.push(x);
 17 | 				});
 18 | 			}
 19 | 			else {
 20 | 				array.push(x);
 21 | 			}
 22 | 			return array;
 23 | 		},[]);
 24 | 	};
 25 | 
 26 | 	var history = [];
 27 | 	var historyLimit = 50;
 28 | 	var previousFocus = null;
 29 | 	var currentFocus = document.activeElement || null;
 30 | 	var traps = [];
 31 | 	var proxies = [];
 32 | 	var pending = null;
 33 | 	var id = 1000000;
 34 | 
 35 | 	/**
 36 | 	 * Returns true if a given element can receive the focus at this particular moment.
 37 | 	 *
 38 | 	 * Computation of what can and cannot receive the focus is a very complex thing.  There is
 39 | 	 * a very helpful chart at https://allyjs.io/data-tables/focusable.html that really
 40 | 	 * highlights the complexity of the issue.  THe focus-traversal-api-polyfill does its
 41 | 	 * best general case to get it right, but does not solve all use cases at this time.  It
 42 | 	 * is the hope of this module that browser manufacturers will implement the proposed
 43 | 	 * specification described at https://github.com/awesomeeng/FocusTraversalAPI in which
 44 | 	 * they will expose the internal isFocusable() method and we can all use the built-in
 45 | 	 * browser implementation and just get it right.
 46 | 	 *
 47 | 	 * In the meantime, this polyfill implementation is doing the best it can. Please let
 48 | 	 * us know if you find edge cases that dont work.
 49 | 	 *
 50 | 	 * If the given element is null or undefined or not otherwise an instance of
 51 | 	 * HTMLElement, this function will always return false.
 52 | 	 *
 53 | 	 * @param  {HTMLElement}  element
 54 | 	 * @return {Boolean}
 55 | 	 */
 56 | 	var isFocusable = function isFocusable(element) {
 57 | 		if (!element) return false;
 58 | 		if (!(element instanceof HTMLElement)) return false;
 59 | 
 60 | 		// these rules apply to the element and all its ancestors...
 61 | 		var all = DT.ancestors(element,true).reverse();
 62 | 		for (var i=0;i<all.length;i++) {
 63 | 			var e = all[i];
 64 | 			if (!e) continue;
 65 | 			if (!(e instanceof HTMLElement)) continue;
 66 | 
 67 | 			// if "inert", not focusable. Note, that inert isn't actually an HTML standard.
 68 | 			var inert = e.inert || false;
 69 | 			if (inert===true) return false;
 70 | 
 71 | 			var styles = window.getComputedStyle(e);
 72 | 
 73 | 			// if style.display = none, not focusable.
 74 | 			var disp = styles.display;
 75 | 			if (disp==="none") return false;
 76 | 
 77 | 			// if style.visibility = hidden, not focusable.
 78 | 			var viz = styles.visibility;
 79 | 			if (viz==="hidden") return false;
 80 | 
 81 | 			// if style.opacity <= 0, not focusable.
 82 | 			var op = styles.opacity;
 83 | 			op = op && parseInt(op) || 1;
 84 | 			if (op<=0) return false;
 85 | 		}
 86 | 
 87 | 		// if tabindex is -1, no focusable.
 88 | 		var ti = element.getAttribute("tabindex") || null;
 89 | 		ti = ti && +ti;
 90 | 		if (ti!==null && ti<0) return false;
 91 | 		if (ti!==null && ti>=0) return true;
 92 | 
 93 | 		// anything disabled is not focusable
 94 | 		var dis = element.hasAttribute("disabled",null);
 95 | 		if (dis) return false;
 96 | 
 97 | 		// Some elements by their very nature are focusable...
 98 | 		var tn = element.tagName;
 99 | 		if (tn==="BUTTON" || tn==="INPUT" || tn==="SELECT" || tn==="TEXTAREA") return true;
100 | 		if (tn==="A" && (element.hasAttribute("href") || element.hasAttribute("xlink:href"))) return true;
101 | 		if (tn==="AUDIO" && element.hasAttribute("controls")) return true;
102 | 		if (tn==="VIDEO" && element.hasAttribute("controls")) return true;
103 | 
104 | 		// Any element that is contenteditable is focusable.
105 | 		var ce = element.getAttribute("contenteditable");
106 | 		if (ce!==null && ce===true) return true;
107 | 
108 | 		return false;
109 | 	};
110 | 
111 | 	/**
112 | 	 * Sets the focus to the given element. This is functionally equivalent to doing
113 | 	 * `element.focus()`. If no element is given, nothing will happen.
114 | 	 *
115 | 	 * Note that the browser does not garauntee that the focus will
116 | 	 * be set to the given element; this is is purely a request.
117 | 	 *
118 | 	 * @param  {HTMLElement} element
119 | 	 * @param  {Object} focusOption
120 | 	 * @return {void}
121 | 	 */
122 | 	var focus = function focus(element,focusOption,immediately) {
123 | 		if (!element || !(element instanceof Element)) return;
124 | 		if (typeof focusOption==="boolean") {
125 | 			immediately = focusOption;
126 | 			focusOption = null;
127 | 		}
128 | 
129 | 		if (pending) clearTimeout(pending);
130 | 		pending = null;
131 | 
132 | 		if (immediately===true) {
133 | 			element.focus(focusOption||{});
134 | 		}
135 | 		else {
136 | 			pending = setTimeout(function(){
137 | 				element.focus(focusOption||{});
138 | 			},0);
139 | 		}
140 | 	};
141 | 
142 | 	/**
143 | 	 * Returns true if the given element currently has the focus. This is functionally
144 | 	 * equivalent to `document.activeElement===element;`.
145 | 	 *
146 | 	 * @param  {HTMLElement}  element
147 | 	 * @return {Boolean}
148 | 	 */
149 | 	var hasFocus = function hasFocus(element) {
150 | 		if (!element || !(element instanceof Element)) return false;
151 | 		return currentFocus===element;
152 | 	};
153 | 
154 | 	/**
155 | 	 * Returns an array of all focusable elements within the given container.  If no
156 | 	 * container is provided `document.body` is assumed.
157 | 	 *
158 | 	 * Note that in very large DOM structures this can be a significantly expensive call.
159 | 	 *
160 | 	 * @param  {HTMLElement|null} container
161 | 	 * @return {Array}
162 | 	 */
163 | 	var list = function list(container){
164 | 		return DT.forwardList(container||document.body,true).filter(function(e){
165 | 			return isFocusable(e);
166 | 		});
167 | 	};
168 | 
169 | 	/**
170 | 	 * Returns the first focusable element in the given container. If no container is
171 | 	 * provided `document.body` is assumed.
172 | 	 *
173 | 	 * @param  {HTMLElement|null} container
174 | 	 * @return {HTMLElement|null}
175 | 	 */
176 | 	var first = function first(container){
177 | 		container = container || document.body;
178 | 		var e = DT.bottom(container,true);
179 | 		if (!e) return;
180 | 		if (isFocusable(e)) return e;
181 | 		e = next(e);
182 | 		if (DT.contains(container,e,true)) return e;
183 | 		return null;
184 | 	};
185 | 
186 | 	/**
187 | 	 * Returns the last focusable element in the given container. If no container is
188 | 	 * provided `document.body` is assumed.
189 | 	 *
190 | 	 * @param  {HTMLElement|null} container
191 | 	 * @return {HTMLElement|null}
192 | 	 */
193 | 	var last = function last(container) {
194 | 		container = container || document.body;
195 | 		var e = DT.bottomLast(container,true);
196 | 		if (!e) return;
197 | 		if (isFocusable(e)) return e;
198 | 		e = previous(e);
199 | 		if (DT.contains(container,e,true)) return e;
200 | 		return null;
201 | 	};
202 | 
203 | 	/**
204 | 	 * Find the first foucsable parent.
205 | 	 *
206 | 	 * @param  {HTMLElement|null} element
207 | 	 * @return {HTMLElement|null}
208 | 	 */
209 | 	var parent = function parent(element) {
210 | 		while (element) {
211 | 			element = DT.up(element,true);
212 | 			if (isFocusable(element)) return element;
213 | 		}
214 | 		return null;
215 | 	};
216 | 
217 | 	/**
218 | 	 * Find the first focusable child. Same as first().
219 | 	 *
220 | 	 * @param  {HTMLElement|null} element
221 | 	 * @return {HTMLElement|null}
222 | 	 */
223 | 	var child = first;
224 | 
225 | 	/**
226 | 	 * Moves the focus forward to the next focusable element.
227 | 	 *
228 | 	 * @param  {Object|null} focusOption
229 | 	 * @return {void}
230 | 	 */
231 | 	var forward = function forward(focusOption) {
232 | 		if (!currentFocus) return;
233 | 
234 | 		var target = next();
235 | 		if (target && target!==currentFocus) focus(target,focusOption||{});
236 | 	};
237 | 
238 | 	/**
239 | 	 * Moves the focus backward to the previous focusable element.
240 | 	 *
241 | 	 * @param  {Object|null} focusOption
242 | 	 * @return {void}
243 | 	 */
244 | 	var backward = function backward(focusOption) {
245 | 		if (!currentFocus) return;
246 | 
247 | 		var target = previous();
248 | 		if (target && target!==currentFocus) focus(target,focusOption||{});
249 | 	};
250 | 
251 | 	/**
252 | 	 * Returns the next focusable element, but does not move the focus to
253 | 	 * that element. If no element is provided, the currently focused
254 | 	 * element is assumed.
255 | 	 *
256 | 	 * @param  {HTMLElement|null}   element
257 | 	 * @return {HTMLElement|null}
258 | 	 */
259 | 	var next = function next(element) {
260 | 		if (!element) element = currentFocus;
261 | 		if (!element || !(element instanceof Element)) return null;
262 | 
263 | 		while (element) {
264 | 			element = DT.forward(element,true);
265 | 			if (element && isFocusable(element)) break;
266 | 		}
267 | 
268 | 		for (var i=0;i<proxies.length;i++) {
269 | 			var p = proxies[i];
270 | 			if (p.source===element) {
271 | 				element = p.target;
272 | 				break;
273 | 			}
274 | 		}
275 | 
276 | 		return element;
277 | 	};
278 | 
279 | 	/**
280 | 	 * Returns the previous focusable element, but does not move the focus to
281 | 	 * that element. If no element is provided, the currently focused
282 | 	 *
283 | 	 * @param  {HTMLElement|null}   element
284 | 	 * @return {HTMLElement|null}
285 | 	 */
286 | 	var previous = function previous(element) {
287 | 		if (!element) element = currentFocus;
288 | 		if (!element || !(element instanceof Element)) return null;
289 | 
290 | 		while (element) {
291 | 			element = DT.backward(element,true);
292 | 			if (element && isFocusable(element)) break;
293 | 		}
294 | 
295 | 		for (var i=0;i<proxies.length;i++) {
296 | 			var p = proxies[i];
297 | 			if (p.source===element) {
298 | 				element = previous(p.source);
299 | 				break;
300 | 			}
301 | 		}
302 | 
303 | 		return element;
304 | 	};
305 | 
306 | 	/**
307 | 	 * Traps the focus within a given container(s). If the focus attempts to
308 | 	 * leave the given container(s), focus is returned to the element that
309 | 	 * last held the focus.
310 | 	 *
311 | 	 * If the given container(s) doesn't have any focusable elements, this
312 | 	 * call will not result in setting the focus trap.
313 | 	 *
314 | 	 * A `trap()` is removed by calling `untrap()` with the same container(s)
315 | 	 * argument.
316 | 	 *
317 | 	 * `trap()` cascades, so calling it multiple times causes the
318 | 	 * trap to narrow. Removing a trap will place the browser back into
319 | 	 * the prior trap state.
320 | 	 *
321 | 	 * You may pass more than one element as arguments to trap and focus
322 | 	 * is considered trapped if any of the elements contains the focused
323 | 	 * element as a descendant.
324 | 	 *
325 | 	 * @param  {HTMLElement} container
326 | 	 * @return {void}
327 | 	 */
328 | 	var trap = function trap(/* element, element, element ... */) {
329 | 		var containers = Array.prototype.slice.call(arguments);
330 | 		if (containers.length<1) return;
331 | 		containers = flatten(containers);
332 | 
333 | 		var bad = containers.some(function(c) {
334 | 			return !(c instanceof HTMLElement);
335 | 		});
336 | 		if (bad) return;
337 | 
338 | 		var existing = traps.filter(function(trap){
339 | 			return trap.containers.every(function(c) {
340 | 				return containers.indexOf(c)>-1;
341 | 			});
342 | 		});
343 | 		if (existing.length>0) return;
344 | 
345 | 		var trap = {
346 | 			containers: containers,
347 | 			last: first(containers[0]),
348 | 			blur: null
349 | 		};
350 | 		traps.unshift(trap);
351 | 
352 | 		focus(trap.last);
353 | 	};
354 | 
355 | 	/**
356 | 	 * Stops trapping focus.
357 | 	 *
358 | 	 * @param  {HTMLElement} container
359 | 	 * @return {void}
360 | 	 */
361 | 	var untrap = function untrap(/* element, element, element ... */) {
362 | 		if (traps.length<1) return;
363 | 
364 | 		var containers = Array.prototype.slice.call(arguments);
365 | 		if (containers.length<1) return;
366 | 
367 | 		containers = flatten(containers);
368 | 
369 | 		var bad = containers.some(function(c) {
370 | 			return !(c instanceof HTMLElement);
371 | 		});
372 | 		if (bad) return;
373 | 
374 | 		var existing = traps.filter(function(trap){
375 | 			return trap.containers.every(function(c) {
376 | 				return containers.indexOf(c)>-1;
377 | 			});
378 | 		});
379 | 		var isFirst = existing && existing.length>0 && traps[0] && traps[0]===existing[0];
380 | 
381 | 		traps = traps.filter(function(trap){
382 | 			return !trap.containers.every(function(c) {
383 | 				return containers.indexOf(c)>-1;
384 | 			});
385 | 		});
386 | 		if (isFirst && traps[0]) focus(traps[0].last);
387 | 	};
388 | 
389 | 	/**
390 | 	 * Order one or more elements using the tabindex attribute. The order
391 | 	 * the elements are given to this function is the order the will occur. This
392 | 	 * will overwrite any existing tabindex on all elements given.
393 | 	 *
394 | 	 * If you give a number as one of the arguments, that number will be used
395 | 	 * as the tabindex for the next element, and then incremented, and used
396 | 	 * for the next element and so on.  If no number is given as the first
397 | 	 * argument, an internal counter will be used instead.
398 | 	 *
399 | 	 * @param  {Array|HTMLElement|Number} element
400 | 	 * @return {void}
401 | 	 */
402 | 	var order = function order(/*element,element,element,etc*/) {
403 | 		var pos = null;
404 | 		var elements = flatten(arguments);
405 | 		elements.forEach(function(e){
406 | 			if (typeof e==="number") {
407 | 				pos = e;
408 | 				return;
409 | 			}
410 | 			else if (e instanceof HTMLElement) {
411 | 				var n = id++;
412 | 				if (pos!==null) n = pos++;
413 | 				e.setAttribute("tabindex",""+n);
414 | 			}
415 | 		});
416 | 	};
417 | 
418 | 	/**
419 | 	 * Sets the given source element to proxy any focus it receives to the
420 | 	 * target element. If the source element given is not focusable, it will
421 | 	 * be made focusable.  The target element must be focusable.
422 | 	 *
423 | 	 * @param  {HTMLElement} source
424 | 	 * @param  {HTMLElement} target
425 | 	 * @return {void}
426 | 	 */
427 | 	var proxy = function proxy(source,target) {
428 | 		if (!source) return;
429 | 		if (!(source instanceof HTMLElement)) return;
430 | 		if (!target) return;
431 | 		if (!(target instanceof HTMLElement)) return;
432 | 		if (!isFocusable(target)) return;
433 | 
434 | 		// clear any existing proxy
435 | 		unproxy(source,target);
436 | 
437 | 		var ti = source.getAttribute("tabindex") || null;
438 | 		ti = ti && parseInt(ti) || null;
439 | 		if (ti===null || ti<0) source.setAttribute("tabindex",0);
440 | 
441 | 		proxies.push({
442 | 			source: source,
443 | 			target: target,
444 | 			sourceTabIndex: ti
445 | 		});
446 | 
447 | 		if (currentFocus===source) focus(target);
448 | 	};
449 | 
450 | 	/**
451 | 	 * Removes an existing proxy.
452 | 	 *
453 | 	 * @param  {HTMLElement} source
454 | 	 * @param  {HTMLElement} target
455 | 	 * @return {void}
456 | 	 */
457 | 	var unproxy = function unproxy(source,target) {
458 | 		proxies = proxies.filter(function(p){
459 | 			if (p.source===source && p.target===target) {
460 | 				if (p.sourceTabIndex!==null) source.setAttribute("tabindex",p.sourceTabIndex);
461 | 				else source.removeAttribute("tabindex");
462 | 				return false;
463 | 			}
464 | 			return true;
465 | 		});
466 | 	};
467 | 
468 | 	document.addEventListener("DOMContentLoaded",function(){
469 | 		document.addEventListener("focus",function(event){
470 | 			var target = event.target;
471 | 			if (event.composedPath) {
472 | 				var path = event.composedPath();
473 | 				if (path.length>0) target = path[0];
474 | 			}
475 | 
476 | 			currentFocus = target;
477 | 
478 | 			var trap = traps[0] || null;
479 | 			if (trap) trap.last = target;
480 | 
481 | 			history.unshift(target);
482 | 			if (historyLimit>-1) history = history.slice(0,historyLimit);
483 | 
484 | 			for (var i=0;i<proxies.length;i++) {
485 | 				var p = proxies[i];
486 | 				if (p.source===target) {
487 | 					focus(p.target);
488 | 					return;
489 | 				}
490 | 			}
491 | 		},true);
492 | 		document.addEventListener("blur",function(event){
493 | 			var target = event.target;
494 | 			if (event.composedPath) {
495 | 				var path = event.composedPath();
496 | 				if (path.length>0) target = path[0];
497 | 			}
498 | 
499 | 			var related = event.relatedTarget;
500 | 			if (related) {
501 | 				var trap = traps[0] || null;
502 | 				if (trap && trap.last) {
503 | 					var anc = DT.ancestors(related,true);
504 | 
505 | 					let found = trap.containers.reduce(function(found,c){
506 | 						if (found) return found;
507 | 						if (anc.indexOf(c)>-1) return true;
508 | 						return false;
509 | 					},false);
510 | 
511 | 					if (!found) focus(trap.last);
512 | 				}
513 | 			}
514 | 
515 | 			previousFocus = target;
516 | 		},true);
517 | 		document.addEventListener("keyup",function(event){
518 | 			if (event.shiftKey && event.keyCode===9) {
519 | 				var source = currentFocus;
520 | 				for (var i=0;i<proxies.length;i++) {
521 | 					var p = proxies[i];
522 | 					if (p.source===source || p.target===source) {
523 | 						focus(previous(p.source));
524 | 						event.preventDefault();
525 | 						return;
526 | 					}
527 | 				}
528 | 			}
529 | 		},true);
530 | 	});
531 | 
532 | 	window.focusManager = {
533 | 		isFocusable: isFocusable,
534 | 		focus: focus,
535 | 		hasFocus: hasFocus,
536 | 		list: list,
537 | 		first: first,
538 | 		last: last,
539 | 		parent: parent,
540 | 		child: child,
541 | 		forward: forward,
542 | 		backward: backward,
543 | 		next: next,
544 | 		previous: previous,
545 | 		trap: trap,
546 | 		untrap: untrap,
547 | 		order: order,
548 | 		proxy: proxy,
549 | 		unproxy: unproxy
550 | 	};
551 | 	Object.defineProperty(window.focusManager,"currentlyFocused",{
552 | 		get: function() {
553 | 			return currentFocus;
554 | 		}
555 | 	});
556 | 	Object.defineProperty(window.focusManager,"previouslyFocused",{
557 | 		get: function() {
558 | 			return previousFocus || null;
559 | 		}
560 | 	});
561 | 	Object.defineProperty(window.focusManager,"history",{
562 | 		get: function() {
563 | 			return [].concat(history);
564 | 		}
565 | 	});
566 | 	Object.defineProperty(window.focusManager,"historyLimit",{
567 | 		get: function() {
568 | 			return historyLimit;
569 | 		},
570 | 		set: function(n) {
571 | 			n = parseInt(n);
572 | 			if (isNaN(n)) return;
573 | 			if (n<-1) return;
574 | 			historyLimit = n;
575 | 
576 | 			if (historyLimit>-1) history = history.slice(0,historyLimit);
577 | 		}
578 | 	});
579 | })();
580 | 


--------------------------------------------------------------------------------
/examples/WebComponents/zeph.min.js:
--------------------------------------------------------------------------------
1 | const $COMPONENTS=Symbol("components"),$CONTEXT=Symbol("context"),$CODE=Symbol("code"),$ELEMENT=Symbol("element"),$SHADOW=Symbol("shadow"),$OBSERVER=Symbol("observer"),$LISTENERS=Symbol("listeners"),$PROXY=Symbol("proxy");let CODE_CONTEXT=null,PENDING={},FIREREADY=null,READY=!1;const IDENTITY_FUNCTION=t=>t,check={not:{undefined:(t,e)=>{if(void 0===t)throw new Error("Undefined "+e+".")},null:(t,e)=>{if(null===t)throw new Error("Null "+e+".")},uon:(t,e)=>{check.not.undefined(t,e),check.not.null(t,e)},empty:(t,e)=>{if("string"==typeof t&&""===t)throw new Error("Empty "+e+".")}},type:(t,e,n)=>{if(typeof t!==e)throw new Error("Invalid "+n+"; must be a "+e+".")},string:(t,e)=>{check.type(t,"string",e)},posstr:(t,e)=>{check.not.uon(t,e),check.string(t,e),check.not.empty(t,e)},number:(t,e)=>{check.type(t,"number",e)},boolean:(t,e)=>{check.type(t,"string",e)},function:(t,e,n)=>{if(!(t instanceof Function))throw new Error("Invalid "+n+"; must be a Function.")},array:(t,e,n)=>{if(!(t instanceof Array))throw new Error("Invalid "+n+"; must be an Array.")}},utils={ready:()=>READY,tryprom:t=>(check.not.uon(t,"argument"),check.function(t,"argument"),new Promise((e,n)=>{try{t(e,n)}catch(t){return n(t)}})),exists:t=>null==t||""===t?Promise.resolve(!1):utils.tryprom(async e=>{(await fetch(t,{method:"HEAD"})).ok?e(!0):e(!1)}),fetch:t=>(check.not.uon(t,"url"),check.not.empty(t,"url"),utils.tryprom(async e=>{let n=await fetch(t);if(n.ok)return e(n);e(void 0)})),fetchText:t=>(check.not.uon(t,"url"),check.not.empty(t,"url"),utils.tryprom(async e=>{let n=await utils.fetch(t);n||e(void 0),e(await n.text())})),resolve:(t,e=document.URL)=>{if(check.not.uon(t,"url"),check.not.empty(t,"url"),!(t instanceof URL)&&"string"!=typeof t)throw new Error("Invalid url; must be a string or URL.");try{return"string"==typeof t&&t.startsWith("data:")?new URL(t):new URL(t,e)}catch(t){return null}},resolveName:(t,e=document.URL,n=".js")=>(""+t).match(/^http:\/\/|^https:\/\/|^ftp:\/\/|^\.\/|^\.\.\//)?utils.tryprom(async i=>{let o=utils.resolve(t,e);if(await utils.exists(o))return i(o);if(await utils.exists(t))return i(t);if(n){let o=t+n,r=utils.resolve(o,e);if(await utils.exists(r))return i(r);if(await utils.exists(o))return i(o)}i(void 0)}):Promise.resolve(void 0)};class ZephComponent{constructor(t,e,n){check.posstr(t,"name"),check.posstr(t,"origin"),check.not.uon(n,"code"),check.function(n,"code");let i={};i.name=t,i.origin=e,this[$CODE]=n,this[$CONTEXT]=i,this[$ELEMENT]=null}get context(){return this[$CONTEXT]}get name(){return this.context.name}get origin(){return this.context.origin}get code(){return this[$CODE]}get defined(){return!!this[$ELEMENT]}get customElementClass(){return this[$ELEMENT]}define(){return utils.tryprom(async t=>{let e=new ZephComponentExecution(this.context,this.code);if(await e.run(),await Promise.all(this.context.pending||[]),this.context.from){let t=ZephComponents.get(this.context.from);if(!t)throw new Error("Component '"+this.context.from+"' not found; inheritence by '"+this.context.name+"' is not possible.");await Promise.all(t.context.pending||[]),this[$CONTEXT]=extend({},t.context,this.context)}this[$ELEMENT]=ZephElementClass.generateClass(this.context),customElements.define(this.name,this[$ELEMENT]),(this.context.aliases||[]).forEach(t=>{customElements.define(t,class extends this[$ELEMENT]{constructor(){super()}})}),fire(this.context&&this.context.lifecycle&&this.context.lifecycle.init||[],this.name,this),t()})}}class ZephComponentExecution{constructor(t,e){check.not.uon(t,"context"),check.not.uon(e,"code"),check.function(e,"code"),this[$CONTEXT]=t,this[$CODE]=e}run(){return utils.tryprom(async t=>{CODE_CONTEXT=this,await this[$CODE].bind(this)(),CODE_CONTEXT=null,t()})}get context(){return this[$CONTEXT]}from(t){check.posstr(t,"fromTagName"),this.context.pending=this.context.pending||[],this.context.pending.push(ZephComponents.waitFor(t)),this.context.from=t}alias(t){check.posstr(t,"aliasName"),this.context.aliases=this.context.aliases||new Set,this.context.aliases.add(t)}html(t,e={}){e=Object.assign({overwrite:!1,noRemote:!1},e||{});let n=utils.tryprom(async n=>{if(!e.noRemote){let e=await utils.resolveName(t,this.context.origin||document.URL.toString(),".html");e&&(t=await utils.fetchText(e))}this.context.html=this.context.html||[],this.context.html.push({content:t,options:e}),n()});this.context.pending=this.context.pending||[],this.context.pending.push(n)}css(t,e={}){e=Object.assign({overwrite:!1,noRemote:!1},e||{});let n=utils.tryprom(async n=>{if(!e.noRemote){let e=await utils.resolveName(t,this.context.origin,".css");e&&(t=await utils.fetchText(e))}this.context.css=this.context.css||[],this.context.css.push({content:t,options:e}),n()});this.context.pending=this.context.pending||[],this.context.pending.push(n)}attribute(t,e){if(check.not.uon(t,"attributeName"),check.string(t),this.context.attributes=this.context.attributes||{},this.context.attributes[t])throw new Error("Attribute '"+t+"' already defined for custom element; cannot have multiple definitions.");this.context.attributes[t]={attributeName:t,initialValue:e}}property(t,e,n){if(check.not.uon(t,"propertyName"),check.string(t),this.context.properties=this.context.properties||{},this.context.properties[t])throw new Error("Property '"+t+"' already defined for custom element; cannot have multiple definitions.");this.context.properties[t]=Object.assign(this.context.properties[t]||{},{propertyName:t,initialValue:e,transformFunction:n,changes:[]})}binding(t,e,n,i){return this.bindingAt(".",t,e,n,i)}bindingAt(t,e,n,i,o){if(t&&e&&n&&void 0===i&&(i=e),check.not.uon(t,"sourceElement"),"string"!=typeof t&&!(t instanceof HTMLElement))throw new Error("Invalid sourceElement; must be a string or an instance of HTMLElement.");if(check.not.uon(e,"sourceName"),check.string(e,"sourceName"),!e.startsWith("$")&&!e.startsWith("@")&&!e.startsWith("."))throw new Error("Invalid sourceName; must start with a '$' or a '@' or a '.'.");if(check.not.uon(n,"targetElement"),"string"!=typeof n&&!(n instanceof HTMLElement))throw new Error("Invalid targetElement; must be a string or an instance of HTMLElement.");if(check.not.uon(i,"targetName"),check.string(i,"targetName"),!i.startsWith("$")&&!i.startsWith("@")&&!i.startsWith("."))throw new Error("Invalid targetName; must start with a '$' or a '@' or a '.'.");null==o&&(o=IDENTITY_FUNCTION),check.not.uon(o,"transformFunction"),check.function(o,"transformFunction");let r=t+":"+e+">"+n+":"+i;this.context.bindings=this.context.bindings||{},this.context.bindings[r]={source:{element:t,name:e},target:{element:n,name:i},transform:o}}onInit(t){check.not.uon(t,"listener"),check.function(t,"listener"),this.context.lifecycle=this.context.lifecycle||{},this.context.lifecycle.init=this.context.lifecycle.init||[],this.context.lifecycle.init.push(t)}onCreate(t){check.not.uon(t,"listener"),check.function(t,"listener"),this.context.lifecycle=this.context.lifecycle||{},this.context.lifecycle.create=this.context.lifecycle.create||[],this.context.lifecycle.create.push(t)}onAdd(t){check.not.uon(t,"listener"),check.function(t,"listener"),this.context.lifecycle=this.context.lifecycle||{},this.context.lifecycle.add=this.context.lifecycle.add||[],this.context.lifecycle.add.push(t)}onRemove(t){check.not.uon(t,"listener"),check.function(t,"listener"),this.context.lifecycle=this.context.lifecycle||{},this.context.lifecycle.remove=this.context.lifecycle.remove||[],this.context.lifecycle.remove.push(t)}onAdopt(t){check.not.uon(t,"listener"),check.function(t,"listener"),this.context.lifecycle=this.context.lifecycle||{},this.context.lifecycle.adopt=this.context.lifecycle.adopt||[],this.context.lifecycle.adopt.push(t)}onAttribute(t,e){check.not.uon(t,"attribute"),check.string(t,"attribute"),check.not.uon(e,"listener"),check.function(e,"listener"),this.context.observed=this.context.observed||[],this.context.observed.push(t),this.context.lifecycle=this.context.lifecycle||{},this.context.lifecycle.attributes=this.context.lifecycle.attributes||{},this.context.lifecycle.attributes[t]=this.context.lifecycle.attributes[t]||[],this.context.lifecycle.attributes[t].push(e)}onProperty(t,e){check.not.uon(t,"attribute"),check.string(t,"attribute"),check.not.uon(e,"listener"),check.function(e,"listener"),this.context.properties=this.context.properties||{},this.context.properties[t]||this.property(t,void 0),this.context.properties[t].changes.push(e)}onEvent(t,e){check.not.uon(t,"eventName"),check.string(t,"eventName"),check.not.uon(e,"listener"),check.function(e,"listener"),this.context.events=this.context.events||[],this.context.events.push({eventName:t,listener:e})}onEventAt(t,e,n){check.not.uon(e,"eventName"),check.string(e,"eventName"),check.not.uon(n,"listener"),check.function(n,"listener"),this.context.eventsAt=this.context.eventsAt||[],this.context.eventsAt.push({selector:t,eventName:e,listener:n})}}class ZephElementClass{static generateClass(t){return class extends HTMLElement{static get observedAttributes(){return t&&t.observed||[]}constructor(){super();let e=this;this[$ELEMENT]=e;let n=this.shadowRoot||this.attachShadow({mode:"open"});this[$SHADOW]=n;let i=n.querySelector("style");i=i?i.textContent:"";let o=n.innerHTML;if((t.html||[]).forEach(t=>{let e=t.content;t.options.overwrite?o=e:o+=e}),n.innerHTML=o,(t.css||[]).forEach(t=>{let e=t.content;t.options.overwrite?i=e:i+=e+"\n"}),i){let t=document.createElement("style");t.textContent=i,n.appendChild(t)}setTimeout(()=>{t.attributes&&Object.values(t.attributes).forEach(t=>{let n=e.hasAttribute(t.attributeName)?e.getAttribute(t.attributeName):t.initialValue;null==n?e.removeAttribute(t.attributeName):e.setAttribute(t.attributeName,t.transformFunction?t.transformFunction(n):n)}),t.properties&&Object.values(t.properties).forEach(t=>{let i=void 0!==e[t.propertyName]?e[t.propertyName]:t.initialValue;propetize(e,t.propertyName,{get:t=>t?t():i,set:(o,r)=>{o=t.transformFunction?t.transformFunction(o):o,r&&(o=r(o)),i=o,(t.changes||[]).forEach(i=>{i(t.propertyName,o,e,n)})}}),e[t.propertyName]=void 0===e[t.propertyName]?t.initialValue:e[t.propertyName]}),fireImmediately(t&&t.lifecycle&&t.lifecycle.create||[],this,this.shadowRoot),t.bindings&&Object.keys(t.bindings).forEach(i=>{let o=t.bindings[i];if(!o)return;"."===o.target.element&&(o.target.element=e);let r=o.source.element;"."===r?r=[e]:"string"==typeof r?r=[...n.querySelectorAll(r)]:r instanceof HTMLElement&&(r=[r]),r.forEach(i=>{let r;if(o.target.name.startsWith("@"))r=(t=>{let e=o.target.name.slice(1);t=o.transform(t),(o.target.element instanceof HTMLElement&&[o.target.element]||[...n.querySelectorAll(o.target.element)]||[]).forEach(n=>{void 0===t?n.removeAttribute(e):n.getAttribute(e)!==t&&n.setAttribute(e,t)})});else if(o.target.name.startsWith("."))r=(t=>{let e=o.target.name.slice(1);t=o.transform(t),(o.target.element instanceof HTMLElement&&[o.target.element]||[...n.querySelectorAll(o.target.element)]||[]).forEach(n=>{void 0===t?delete n[e]:n[e]!==t&&(n[e]=t)})});else{if("$"!==o.target.name)return void console.warn("Unable to handle binding to '"+o.target.name+"'; Must start with '@' or '$' or '.'.");r=(t=>{void 0!==(t=o.transform(t))&&(o.target.element instanceof HTMLElement&&[o.target.element]||[...n.querySelectorAll(o.target.element)]||[]).forEach(e=>{e.textContent!==t&&(e.textContent=null==t?"":t)})})}i[$OBSERVER]||(i[$OBSERVER]=new ZephElementObserver(i),i[$OBSERVER].start());let s=i[$OBSERVER];if(o.source.name.startsWith("@")){let t=o.source.name.slice(1);if(i.hasAttribute(t)){let e=i.getAttribute(t);r(e,t,i)}s.addAttributeObserver(t,r)}else if(o.source.name.startsWith(".")){let i=o.source.name.slice(1);if(t.properties=t.properties||{},!t.properties[i]){t.properties[i]={propertyName:i,changes:[],value:e[i]};let o=t.properties[i];propetize(e,i,{get:t=>t?t():o.value,set:(t,i)=>{let r=o.transformFunction?o.transformFunction(t):t;i&&i(r),o.value=r,(o.changes||[]).forEach(t=>{t(o.propertyName,r,e,n)})}})}let s=t.properties[i];s.changes=s.changes||[],s.changes.push((t,e)=>{r(e)})}else{if("$"!==o.source.name)return void console.warn("Unable to handle binding to '"+o.target.name+"'; Must start with '@' or '$' or '.'.");{let t=i.textContent;r(t,null,i),s.addContentObserver(r)}}})}),t.events&&t.events.forEach(t=>{this.addEventListener(t.eventName,i=>{t.listener.call(e,i,e,n)})}),t.eventsAt&&t.eventsAt.forEach(t=>{[...n.querySelectorAll(t.selector)].forEach(i=>{i.addEventListener(t.eventName,o=>{t.listener.call(i,o,i,e,n)})})})},0)}get element(){return this[$ELEMENT]}get content(){return this[$SHADOW]}connectedCallback(){fire(t&&t.lifecycle&&t.lifecycle.add||[],this,this.shadowRoot)}disconnectedCallback(){fire(t&&t.lifecycle&&t.lifecycle.remove||[],this,this.shadowRoot)}adoptedCallback(){fire(t&&t.lifecycle&&t.lifecycle.adopt||[],this,this.shadowRoot)}attributeChangedCallback(e,n,i){fire(t&&t.lifecycle&&t.lifecycle.attributes&&t.lifecycle.attributes[e]||[],n,i,this,this.shadowRoot)}}}}class ZephElementObserver{constructor(t){if(!t)throw new Error("Missing element.");if(!(t instanceof HTMLElement))throw new Error("Invalid element; must be an instance of HTMLElement.");this.element=t,this.attributes={},this.content=[],this.observer=new MutationObserver(this.handleMutation.bind(this))}addAttributeObserver(t,e){check.not.uon(t,"attribute"),check.string(t,"attribute"),check.not.uon(e,"handler"),check.function(e,"handler"),this.attributes[t]=this.attributes[t]||[],this.attributes[t].push(e)}removeAttributeObserver(t,e){check.not.uon(t,"attribute"),check.string(t,"attribute"),check.not.uon(e,"handler"),check.function(e,"handler"),this.attributes[t]&&(this.attributes[t]=this.attributes[t].filter(t=>t!==e),this.attributes[t].length<1&&delete this.attributes[t])}removeAllAttributeObservers(t){if(t&&"string"!=typeof t)throw new Error("Invalid attribute; must be a string.");t?delete this.attributes[t]:this.attributes={}}addContentObserver(t){check.not.uon(t,"handler"),check.function(t,"handler"),this.content.push(t)}removeContentObserver(t){check.not.uon(t,"handler"),check.function(t,"handler"),this.content=this.content.filter(e=>e!==t)}removeAllContentObservers(){this.content=[]}start(){this.observer.observe(this.element,{attributes:!0,characterData:!0,childList:!0})}stop(){this.observer.disconnect()}handleMutation(t){t.forEach(t=>{"attributes"===t.type?this.handleAttributeMutation(t):this.handleContentMutation(t)})}handleAttributeMutation(t){let e=t.attributeName;if(!this.attributes[e]||this.attributes[e].length<1)return;let n=this.element.getAttribute(e);this.attributes[e].forEach(t=>{t(n,e,this.element)})}handleContentMutation(){if(this.content.length<1)return;let t=this.element.textContent;this.content.forEach(e=>{e(t,this.element)})}}class ZephComponentsClass{constructor(){this[$COMPONENTS]={},this[$PROXY]=new Proxy(this[$COMPONENTS],{has:(t,e)=>!!t[e],get:(t,e)=>t[e]||void 0,ownKeys:t=>Object.keys(t)}),this[$OBSERVER]=[]}get components(){return this[$PROXY]}get names(){return Object.keys(this[$COMPONENTS])}has(t){return check.posstr(t,"name"),!!this[$COMPONENTS][t]}get(t){return check.posstr(t,"name"),this[$COMPONENTS][t]}waitFor(t){return check.posstr(t,"name"),this[$COMPONENTS][t]?Promise.resolve():new Promise((e,n)=>{this[$OBSERVER].push({name:t,resolve:e,reject:n})})}define(t,e){if(check.posstr(t,"name"),check.not.uon(e,"code"),check.function(e,"code"),this[$COMPONENTS][t])throw new Error("Component already defined.");let n=document.URL.toString(),i=new Error;if(i.fileName&&(n=i.filename),i.stack){for(i=(i=i.stack.split(/\r\n|\n/g)).reverse();i.length>0;){let t=i.shift();if(t&&t.match(/\w+:/g)){i=t=(t=t.trim().replace(/^.*?(?=\w+:)/,"")).replace(/:\d+$|:\d+\)$|:\d+:\d+$|:\d+:\d+\)$/,"");break}}n=i}return PENDING["component:"+n]=!0,document.dispatchEvent(new CustomEvent("zeph:component:loading",{bubbles:!1,detail:t})),utils.tryprom(async i=>{let o=new ZephComponent(t,n,e);this[$COMPONENTS][t]=o,await o.define(),this[$OBSERVER]=this[$OBSERVER].filter(e=>(e.name===t&&e.resolve(),e.name!==t)),delete PENDING["component:"+n],document.dispatchEvent(new CustomEvent("zeph:component:defined",{bubbles:!1,detail:{name:t,component:o}})),fireZephReady(),i(o)})}undefine(t){check.posstr(t,"name");let e=this[$COMPONENTS][t];e&&(delete this[$COMPONENTS][t],document.dispatchEvent(new CustomEvent("zeph:component:undefined",{bubbles:!1,detail:{name:t,component:e}})))}}class ZephService{constructor(){this[$LISTENERS]=new Map,this.on=this.addEventListener,this.once=((t,e)=>{this.addEventListner(t,(t,...n)=>{this.removeEventListener(t,e),e.apply(e,n)})})}fire(t,...e){(this[$LISTENERS].get(t)||[]).forEach(n=>{setTimeout(()=>{n.apply(n,[t,...e])},0)})}addEventListener(t,e){let n=this[$LISTENERS].get(t)||[];n.push(e),this[$LISTENERS].set(t,n)}removeEventListener(t,e){let n=this[$LISTENERS].get(t)||[];n=n.filter(t=>t!==e),this[$LISTENERS].set(t,n)}on(t,e){return this.addEventListener(t,e)}once(t,e){return this.addEventListner(t,(t,...n)=>{this.removeEventListener(t,e),e.apply(e,n)})}off(t,e){return this.removeEventListener(t,e)}}const extend=function t(e,...n){return null==e&&(e={}),n.forEach(n=>{Object.keys(n).forEach(i=>{let o=n[i],r=e[i];void 0!==o&&(null===o?e[i]=null:o instanceof Promise?e[i]=o:o instanceof Function?e[i]=o:o instanceof RegExp?e[i]=o:o instanceof Date?e[i]=new Date(o):o instanceof Array?e[i]=[].concat(r||[],o):e[i]="object"==typeof o?t(r,o):o)})}),e},fire=function(t,...e){(t=t&&!(t instanceof Array)&&[t]||t||[]).forEach(t=>{setTimeout(()=>t.apply(t,e),0)})},fireImmediately=function(t,...e){(t=t&&!(t instanceof Array)&&[t]||t||[]).forEach(t=>t.apply(t,e))},fireZephReady=function(){FIREREADY&&clearTimeout(FIREREADY),FIREREADY=setTimeout(()=>{Object.keys(PENDING).length<1&&(READY=!0,document.dispatchEvent(new CustomEvent("zeph:ready",{bubbles:!1})))},10)},getPropertyDescriptor=function(t,e){for(;;){if(null===t)return null;let n=Object.getOwnPropertyDescriptor(t,e);if(n)return n;t=Object.getPrototypeOf(t)}},propetize=function(t,e,n){check.not.uon(t,"object"),check.not.uon(e,"propertyName"),check.string(e,"propertyName"),check.not.uon(n,"descriptor");let i=getPropertyDescriptor(t,e),o=Object.assign({},i||{},n);return i&&n.get&&(delete o.value,delete o.writable,o.get=(()=>{let t=i.get||null;return n.get(t)})),i&&n.set&&(delete o.writable,o.set=(t=>{let e=i.set||null;return n.set(t,e)})),Object.defineProperty(t,e,o),o},contextCall=function(t){return check.posstr(t,"name"),{[t]:function(){if(!CODE_CONTEXT)throw new Error(t+"() may only be used within the ZephComponent.define() method.");return CODE_CONTEXT[t].apply(CODE_CONTEXT,arguments)}}[t]},from=contextCall("from"),alias=contextCall("alias"),html=contextCall("html"),css=contextCall("css"),attribute=contextCall("attribute"),property=contextCall("property"),bind=contextCall("binding"),bindAt=contextCall("bindingAt"),onInit=contextCall("onInit"),onCreate=contextCall("onCreate"),onAdd=contextCall("onAdd"),onRemove=contextCall("onRemove"),onAdopt=contextCall("onAdopt"),onAttribute=contextCall("onAttribute"),onProperty=contextCall("onProperty"),onEvent=contextCall("onEvent"),onEventAt=contextCall("onEventAt"),ZephComponents=new ZephComponentsClass;export{ZephComponents,ZephService,utils as ZephUtils};export{from,alias,html,css,attribute,property,bind,bindAt,onInit,onCreate,onAdd,onRemove,onAdopt,onAttribute,onProperty,onEvent,onEventAt};window.Zeph={ZephComponents:ZephComponents,ZephService:ZephService,ZephUtils:utils};
2 | 


--------------------------------------------------------------------------------
/focus-traversal-api-polyfill.full.js:
--------------------------------------------------------------------------------
  1 | (function (){
  2 | 	var first = function first(element,delveShadow) {
  3 | 		if (!element) throw new Error("Invalid element.");
  4 | 		return element.firstElementChild || delveShadow && element.shadowRoot && element.shadowRoot.firstElementChild || null;
  5 | 	};
  6 | 	var down = first;
  7 | 
  8 | 	var last = function last(element,delveShadow) {
  9 | 		if (!element) throw new Error("Invalid element.");
 10 | 		return delveShadow && element.shadowRoot && element.shadowRoot.lastElementChild || element.lastElementChild || null;
 11 | 	};
 12 | 	var downLast = last;
 13 | 
 14 | 	var up = function up(element,delveShadow) {
 15 | 		if (!element) throw new Error("Invalid element.");
 16 | 		return element.parentElement || delveShadow && element.parentNode instanceof DocumentFragment && element.parentNode.host || null;
 17 | 	};
 18 | 
 19 | 	var top = function top(element,delveShadow) {
 20 | 		if (!element) throw new Error("Invalid element.");
 21 | 		while(true) {
 22 | 			var e = up(element,delveShadow);
 23 | 			if (!e) break;
 24 | 			element = e;
 25 | 		}
 26 | 		return element;
 27 | 	};
 28 | 
 29 | 	var bottom = function bottom(element,delveShadow) {
 30 | 		if (!element) throw new Error("Invalid element.");
 31 | 		while (true) {
 32 | 			var e = down(element,delveShadow);
 33 | 			if (!e) break;
 34 | 			element = e;
 35 | 		}
 36 | 		return element;
 37 | 	};
 38 | 
 39 | 	var bottomLast = function bottomLast(element,delveShadow) {
 40 | 		if (!element) throw new Error("Invalid element.");
 41 | 		while (true) {
 42 | 			var e = downLast(element,delveShadow);
 43 | 			if (!e) break;
 44 | 			element = e;
 45 | 		}
 46 | 		return element;
 47 | 	};
 48 | 
 49 | 	var next = function next(element,delveShadow) {
 50 | 		if (!element) throw new Error("Invalid element.");
 51 | 
 52 | 		var c = element.firstElementChild || null;
 53 | 		if (c) return c;
 54 | 
 55 | 		var sc = delveShadow && element.shadowRoot && element.shadowRoot.firstElementChild || null;
 56 | 		if (sc) return element.shadowRoot.firstElementChild;
 57 | 
 58 | 		var sib = element.nextElementSibling || null;
 59 | 		if (sib) return sib;
 60 | 
 61 | 		var e = element;
 62 | 		while (true) {
 63 | 			e = up(e,delveShadow);
 64 | 			if (!e || e===element) return null;
 65 | 
 66 | 			sib = e.nextElementSibling;
 67 | 			if (sib) return sib;
 68 | 		}
 69 | 	};
 70 | 
 71 | 	var prev = function prev(element,delveShadow) {
 72 | 		if (!element) throw new Error("Invalid element.");
 73 | 
 74 | 		var sib = element.previousElementSibling;
 75 | 		if (sib) return bottomLast(sib,delveShadow);
 76 | 
 77 | 		var sc = delveShadow && !element.parentElement && element.parentNode && element.parentNode instanceof DocumentFragment && element.parentNode.host || null;
 78 | 		if (sc && sc.lastElementChild) return bottom(sc.lastElementChild,delveShadow);
 79 | 
 80 | 		var u = up(element,delveShadow);
 81 | 		return u;
 82 | 	};
 83 | 
 84 | 	var descendants = function descendants(element,delveShadow) {
 85 | 		if (!element) throw new Error("Invalid element.");
 86 | 
 87 | 		var desc = [];
 88 | 
 89 | 		var children = Array.prototype.slice.call(element.children);
 90 | 		children.forEach(function(c){
 91 | 			desc = desc.concat(c,descendants(c,delveShadow));
 92 | 		});
 93 | 
 94 | 		if (delveShadow && element.shadowRoot) {
 95 | 			var shadows = Array.prototype.slice.call(element.shadowRoot.children);
 96 | 			shadows.forEach(function(c){
 97 | 				desc = desc.concat(c,descendants(c,delveShadow));
 98 | 			});
 99 | 		}
100 | 
101 | 		return desc;
102 | 	};
103 | 
104 | 	var ancestors = function ancestors(element,delveShadow) {
105 | 		if (!element) throw new Error("Invalid element.");
106 | 
107 | 		var ansc = [];
108 | 		var e = element;
109 | 		while (e) {
110 | 			e = up(e,delveShadow);
111 | 			if (!e) break;
112 | 			ansc.push(e);
113 | 		}
114 | 		return ansc;
115 | 	};
116 | 
117 | 	var forwardList = function forwardList(element,delveShadow) {
118 | 		if (!element) throw new Error("Invalid element.");
119 | 		var elements = [];
120 | 
121 | 		var e = element;
122 | 		while (true) {
123 | 			if (!e) break;
124 | 			e = next(e,delveShadow);
125 | 			if (!e || e===element || !contains(element,e,delveShadow)) break;
126 | 			elements.push(e);
127 | 		}
128 | 		return elements;
129 | 	};
130 | 
131 | 	var backwardList = function backwardList(element,delveShadow) {
132 | 		if (!element) throw new Error("Invalid element.");
133 | 		return forwardList(element,delveShadow).reverse();
134 | 	};
135 | 
136 | 	var contains = function contains(container,element,delveShadow) {
137 | 		if (!container && !(container instanceof HTMLElement)) return false;
138 | 		if (!element && !(element instanceof HTMLElement)) return false;
139 | 
140 | 		if (!delveShadow) return container.contains(element);
141 | 
142 | 		var ancs = ancestors(element,true);
143 | 		return ancs.indexOf(container)>-1;
144 | 	};
145 | 
146 | 	var dom = {
147 | 		first: first,
148 | 		last: last,
149 | 		up: up,
150 | 		down: first,
151 | 		downLast: last,
152 | 		next: next,
153 | 		forward: next,
154 | 		prev: prev,
155 | 		previous: prev,
156 | 		backward: prev,
157 | 		top: top,
158 | 		bottom: bottom,
159 | 		bottomLast: bottomLast,
160 | 		descendants: descendants,
161 | 		ancestors: ancestors,
162 | 		forwardList: forwardList,
163 | 		backwardList: backwardList,
164 | 		contains: contains
165 | 	};
166 | 
167 | 	// can be used in node, mostly for testing
168 | 	// eslint-disable-next-line no-undef
169 | 	if (typeof module!=="undefined" && module && module.exports) {
170 | 		// eslint-disable-next-line no-undef
171 | 		module.exports = dom;
172 | 	}
173 | 
174 | 	// creates window.DOMTraversal for usage in browsers.
175 | 	if (typeof window!=="undefined" && window) {
176 | 		window.DOMTraversal = window.DOMTraversal || dom;
177 | 	}
178 | })();
179 | // requires DOMTraversal.
180 | 
181 | (function (){
182 | 	if (typeof window==="undefined" || window.focusManager) return;
183 | 
184 | 	var DT = window.DOMTraversal;
185 | 
186 | 	// array helpers
187 | 	var flatten = function flatten(array) {
188 | 		if (!array) throw new Error("Missing array.");
189 | 		if (!(array instanceof Array)) array = Array.prototype.slice.call(array);
190 | 
191 | 		return array.reduce(function(array,x) {
192 | 			if (x instanceof Array) {
193 | 				this.flatten(x).forEach(function(x) {
194 | 					array.push(x);
195 | 				});
196 | 			}
197 | 			else {
198 | 				array.push(x);
199 | 			}
200 | 			return array;
201 | 		},[]);
202 | 	};
203 | 
204 | 	var history = [];
205 | 	var historyLimit = 50;
206 | 	var previousFocus = null;
207 | 	var currentFocus = document.activeElement || null;
208 | 	var traps = [];
209 | 	var proxies = [];
210 | 	var pending = null;
211 | 	var id = 1000000;
212 | 
213 | 	/**
214 | 	 * Returns true if a given element can receive the focus at this particular moment.
215 | 	 *
216 | 	 * Computation of what can and cannot receive the focus is a very complex thing.  There is
217 | 	 * a very helpful chart at https://allyjs.io/data-tables/focusable.html that really
218 | 	 * highlights the complexity of the issue.  THe focus-traversal-api-polyfill does its
219 | 	 * best general case to get it right, but does not solve all use cases at this time.  It
220 | 	 * is the hope of this module that browser manufacturers will implement the proposed
221 | 	 * specification described at https://github.com/awesomeeng/FocusTraversalAPI in which
222 | 	 * they will expose the internal isFocusable() method and we can all use the built-in
223 | 	 * browser implementation and just get it right.
224 | 	 *
225 | 	 * In the meantime, this polyfill implementation is doing the best it can. Please let
226 | 	 * us know if you find edge cases that dont work.
227 | 	 *
228 | 	 * If the given element is null or undefined or not otherwise an instance of
229 | 	 * HTMLElement, this function will always return false.
230 | 	 *
231 | 	 * @param  {HTMLElement}  element
232 | 	 * @return {Boolean}
233 | 	 */
234 | 	var isFocusable = function isFocusable(element) {
235 | 		if (!element) return false;
236 | 		if (!(element instanceof HTMLElement)) return false;
237 | 
238 | 		// these rules apply to the element and all its ancestors...
239 | 		var all = DT.ancestors(element,true).reverse();
240 | 		for (var i=0;i<all.length;i++) {
241 | 			var e = all[i];
242 | 			if (!e) continue;
243 | 			if (!(e instanceof HTMLElement)) continue;
244 | 
245 | 			// if "inert", not focusable. Note, that inert isn't actually an HTML standard.
246 | 			var inert = e.inert || false;
247 | 			if (inert===true) return false;
248 | 
249 | 			var styles = window.getComputedStyle(e);
250 | 
251 | 			// if style.display = none, not focusable.
252 | 			var disp = styles.display;
253 | 			if (disp==="none") return false;
254 | 
255 | 			// if style.visibility = hidden, not focusable.
256 | 			var viz = styles.visibility;
257 | 			if (viz==="hidden") return false;
258 | 
259 | 			// if style.opacity <= 0, not focusable.
260 | 			var op = styles.opacity;
261 | 			op = op && parseInt(op) || 1;
262 | 			if (op<=0) return false;
263 | 		}
264 | 
265 | 		// if tabindex is -1, no focusable.
266 | 		var ti = element.getAttribute("tabindex") || null;
267 | 		ti = ti && +ti;
268 | 		if (ti!==null && ti<0) return false;
269 | 		if (ti!==null && ti>=0) return true;
270 | 
271 | 		// anything disabled is not focusable
272 | 		var dis = element.hasAttribute("disabled",null);
273 | 		if (dis) return false;
274 | 
275 | 		// Some elements by their very nature are focusable...
276 | 		var tn = element.tagName;
277 | 		if (tn==="BUTTON" || tn==="INPUT" || tn==="SELECT" || tn==="TEXTAREA") return true;
278 | 		if (tn==="A" && (element.hasAttribute("href") || element.hasAttribute("xlink:href"))) return true;
279 | 		if (tn==="AUDIO" && element.hasAttribute("controls")) return true;
280 | 		if (tn==="VIDEO" && element.hasAttribute("controls")) return true;
281 | 
282 | 		// Any element that is contenteditable is focusable.
283 | 		var ce = element.getAttribute("contenteditable");
284 | 		if (ce!==null && ce===true) return true;
285 | 
286 | 		return false;
287 | 	};
288 | 
289 | 	/**
290 | 	 * Sets the focus to the given element. This is functionally equivalent to doing
291 | 	 * `element.focus()`. If no element is given, nothing will happen.
292 | 	 *
293 | 	 * Note that the browser does not garauntee that the focus will
294 | 	 * be set to the given element; this is is purely a request.
295 | 	 *
296 | 	 * @param  {HTMLElement} element
297 | 	 * @param  {Object} focusOption
298 | 	 * @return {void}
299 | 	 */
300 | 	var focus = function focus(element,focusOption,immediately) {
301 | 		if (!element || !(element instanceof Element)) return;
302 | 		if (typeof focusOption==="boolean") {
303 | 			immediately = focusOption;
304 | 			focusOption = null;
305 | 		}
306 | 
307 | 		if (pending) clearTimeout(pending);
308 | 		pending = null;
309 | 
310 | 		if (immediately===true) {
311 | 			element.focus(focusOption||{});
312 | 		}
313 | 		else {
314 | 			pending = setTimeout(function(){
315 | 				element.focus(focusOption||{});
316 | 			},0);
317 | 		}
318 | 	};
319 | 
320 | 	/**
321 | 	 * Returns true if the given element currently has the focus. This is functionally
322 | 	 * equivalent to `document.activeElement===element;`.
323 | 	 *
324 | 	 * @param  {HTMLElement}  element
325 | 	 * @return {Boolean}
326 | 	 */
327 | 	var hasFocus = function hasFocus(element) {
328 | 		if (!element || !(element instanceof Element)) return false;
329 | 		return currentFocus===element;
330 | 	};
331 | 
332 | 	/**
333 | 	 * Returns an array of all focusable elements within the given container.  If no
334 | 	 * container is provided `document.body` is assumed.
335 | 	 *
336 | 	 * Note that in very large DOM structures this can be a significantly expensive call.
337 | 	 *
338 | 	 * @param  {HTMLElement|null} container
339 | 	 * @return {Array}
340 | 	 */
341 | 	var list = function list(container){
342 | 		return DT.forwardList(container||document.body,true).filter(function(e){
343 | 			return isFocusable(e);
344 | 		});
345 | 	};
346 | 
347 | 	/**
348 | 	 * Returns the first focusable element in the given container. If no container is
349 | 	 * provided `document.body` is assumed.
350 | 	 *
351 | 	 * @param  {HTMLElement|null} container
352 | 	 * @return {HTMLElement|null}
353 | 	 */
354 | 	var first = function first(container){
355 | 		container = container || document.body;
356 | 		var e = DT.bottom(container,true);
357 | 		if (!e) return;
358 | 		if (isFocusable(e)) return e;
359 | 		e = next(e);
360 | 		if (DT.contains(container,e,true)) return e;
361 | 		return null;
362 | 	};
363 | 
364 | 	/**
365 | 	 * Returns the last focusable element in the given container. If no container is
366 | 	 * provided `document.body` is assumed.
367 | 	 *
368 | 	 * @param  {HTMLElement|null} container
369 | 	 * @return {HTMLElement|null}
370 | 	 */
371 | 	var last = function last(container) {
372 | 		container = container || document.body;
373 | 		var e = DT.bottomLast(container,true);
374 | 		if (!e) return;
375 | 		if (isFocusable(e)) return e;
376 | 		e = previous(e);
377 | 		if (DT.contains(container,e,true)) return e;
378 | 		return null;
379 | 	};
380 | 
381 | 	/**
382 | 	 * Find the first foucsable parent.
383 | 	 *
384 | 	 * @param  {HTMLElement|null} element
385 | 	 * @return {HTMLElement|null}
386 | 	 */
387 | 	var parent = function parent(element) {
388 | 		while (element) {
389 | 			element = DT.up(element,true);
390 | 			if (isFocusable(element)) return element;
391 | 		}
392 | 		return null;
393 | 	};
394 | 
395 | 	/**
396 | 	 * Find the first focusable child. Same as first().
397 | 	 *
398 | 	 * @param  {HTMLElement|null} element
399 | 	 * @return {HTMLElement|null}
400 | 	 */
401 | 	var child = first;
402 | 
403 | 	/**
404 | 	 * Moves the focus forward to the next focusable element.
405 | 	 *
406 | 	 * @param  {Object|null} focusOption
407 | 	 * @return {void}
408 | 	 */
409 | 	var forward = function forward(focusOption) {
410 | 		if (!currentFocus) return;
411 | 
412 | 		var target = next();
413 | 		if (target && target!==currentFocus) focus(target,focusOption||{});
414 | 	};
415 | 
416 | 	/**
417 | 	 * Moves the focus backward to the previous focusable element.
418 | 	 *
419 | 	 * @param  {Object|null} focusOption
420 | 	 * @return {void}
421 | 	 */
422 | 	var backward = function backward(focusOption) {
423 | 		if (!currentFocus) return;
424 | 
425 | 		var target = previous();
426 | 		if (target && target!==currentFocus) focus(target,focusOption||{});
427 | 	};
428 | 
429 | 	/**
430 | 	 * Returns the next focusable element, but does not move the focus to
431 | 	 * that element. If no element is provided, the currently focused
432 | 	 * element is assumed.
433 | 	 *
434 | 	 * @param  {HTMLElement|null}   element
435 | 	 * @return {HTMLElement|null}
436 | 	 */
437 | 	var next = function next(element) {
438 | 		if (!element) element = currentFocus;
439 | 		if (!element || !(element instanceof Element)) return null;
440 | 
441 | 		while (element) {
442 | 			element = DT.forward(element,true);
443 | 			if (element && isFocusable(element)) break;
444 | 		}
445 | 
446 | 		for (var i=0;i<proxies.length;i++) {
447 | 			var p = proxies[i];
448 | 			if (p.source===element) {
449 | 				element = p.target;
450 | 				break;
451 | 			}
452 | 		}
453 | 
454 | 		return element;
455 | 	};
456 | 
457 | 	/**
458 | 	 * Returns the previous focusable element, but does not move the focus to
459 | 	 * that element. If no element is provided, the currently focused
460 | 	 *
461 | 	 * @param  {HTMLElement|null}   element
462 | 	 * @return {HTMLElement|null}
463 | 	 */
464 | 	var previous = function previous(element) {
465 | 		if (!element) element = currentFocus;
466 | 		if (!element || !(element instanceof Element)) return null;
467 | 
468 | 		while (element) {
469 | 			element = DT.backward(element,true);
470 | 			if (element && isFocusable(element)) break;
471 | 		}
472 | 
473 | 		for (var i=0;i<proxies.length;i++) {
474 | 			var p = proxies[i];
475 | 			if (p.source===element) {
476 | 				element = previous(p.source);
477 | 				break;
478 | 			}
479 | 		}
480 | 
481 | 		return element;
482 | 	};
483 | 
484 | 	/**
485 | 	 * Traps the focus within a given container(s). If the focus attempts to
486 | 	 * leave the given container(s), focus is returned to the element that
487 | 	 * last held the focus.
488 | 	 *
489 | 	 * If the given container(s) doesn't have any focusable elements, this
490 | 	 * call will not result in setting the focus trap.
491 | 	 *
492 | 	 * A `trap()` is removed by calling `untrap()` with the same container(s)
493 | 	 * argument.
494 | 	 *
495 | 	 * `trap()` cascades, so calling it multiple times causes the
496 | 	 * trap to narrow. Removing a trap will place the browser back into
497 | 	 * the prior trap state.
498 | 	 *
499 | 	 * You may pass more than one element as arguments to trap and focus
500 | 	 * is considered trapped if any of the elements contains the focused
501 | 	 * element as a descendant.
502 | 	 *
503 | 	 * @param  {HTMLElement} container
504 | 	 * @return {void}
505 | 	 */
506 | 	var trap = function trap(/* element, element, element ... */) {
507 | 		var containers = Array.prototype.slice.call(arguments);
508 | 		if (containers.length<1) return;
509 | 		containers = flatten(containers);
510 | 
511 | 		var bad = containers.some(function(c) {
512 | 			return !(c instanceof HTMLElement);
513 | 		});
514 | 		if (bad) return;
515 | 
516 | 		var existing = traps.filter(function(trap){
517 | 			return trap.containers.every(function(c) {
518 | 				return containers.indexOf(c)>-1;
519 | 			});
520 | 		});
521 | 		if (existing.length>0) return;
522 | 
523 | 		var trap = {
524 | 			containers: containers,
525 | 			last: first(containers[0]),
526 | 			blur: null
527 | 		};
528 | 		traps.unshift(trap);
529 | 
530 | 		focus(trap.last);
531 | 	};
532 | 
533 | 	/**
534 | 	 * Stops trapping focus.
535 | 	 *
536 | 	 * @param  {HTMLElement} container
537 | 	 * @return {void}
538 | 	 */
539 | 	var untrap = function untrap(/* element, element, element ... */) {
540 | 		if (traps.length<1) return;
541 | 
542 | 		var containers = Array.prototype.slice.call(arguments);
543 | 		if (containers.length<1) return;
544 | 
545 | 		containers = flatten(containers);
546 | 
547 | 		var bad = containers.some(function(c) {
548 | 			return !(c instanceof HTMLElement);
549 | 		});
550 | 		if (bad) return;
551 | 
552 | 		var existing = traps.filter(function(trap){
553 | 			return trap.containers.every(function(c) {
554 | 				return containers.indexOf(c)>-1;
555 | 			});
556 | 		});
557 | 		var isFirst = existing && existing.length>0 && traps[0] && traps[0]===existing[0];
558 | 
559 | 		traps = traps.filter(function(trap){
560 | 			return !trap.containers.every(function(c) {
561 | 				return containers.indexOf(c)>-1;
562 | 			});
563 | 		});
564 | 		if (isFirst && traps[0]) focus(traps[0].last);
565 | 	};
566 | 
567 | 	/**
568 | 	 * Order one or more elements using the tabindex attribute. The order
569 | 	 * the elements are given to this function is the order the will occur. This
570 | 	 * will overwrite any existing tabindex on all elements given.
571 | 	 *
572 | 	 * If you give a number as one of the arguments, that number will be used
573 | 	 * as the tabindex for the next element, and then incremented, and used
574 | 	 * for the next element and so on.  If no number is given as the first
575 | 	 * argument, an internal counter will be used instead.
576 | 	 *
577 | 	 * @param  {Array|HTMLElement|Number} element
578 | 	 * @return {void}
579 | 	 */
580 | 	var order = function order(/*element,element,element,etc*/) {
581 | 		var pos = null;
582 | 		var elements = flatten(arguments);
583 | 		elements.forEach(function(e){
584 | 			if (typeof e==="number") {
585 | 				pos = e;
586 | 				return;
587 | 			}
588 | 			else if (e instanceof HTMLElement) {
589 | 				var n = id++;
590 | 				if (pos!==null) n = pos++;
591 | 				e.setAttribute("tabindex",""+n);
592 | 			}
593 | 		});
594 | 	};
595 | 
596 | 	/**
597 | 	 * Sets the given source element to proxy any focus it receives to the
598 | 	 * target element. If the source element given is not focusable, it will
599 | 	 * be made focusable.  The target element must be focusable.
600 | 	 *
601 | 	 * @param  {HTMLElement} source
602 | 	 * @param  {HTMLElement} target
603 | 	 * @return {void}
604 | 	 */
605 | 	var proxy = function proxy(source,target) {
606 | 		if (!source) return;
607 | 		if (!(source instanceof HTMLElement)) return;
608 | 		if (!target) return;
609 | 		if (!(target instanceof HTMLElement)) return;
610 | 		if (!isFocusable(target)) return;
611 | 
612 | 		// clear any existing proxy
613 | 		unproxy(source,target);
614 | 
615 | 		var ti = source.getAttribute("tabindex") || null;
616 | 		ti = ti && parseInt(ti) || null;
617 | 		if (ti===null || ti<0) source.setAttribute("tabindex",0);
618 | 
619 | 		proxies.push({
620 | 			source: source,
621 | 			target: target,
622 | 			sourceTabIndex: ti
623 | 		});
624 | 
625 | 		if (currentFocus===source) focus(target);
626 | 	};
627 | 
628 | 	/**
629 | 	 * Removes an existing proxy.
630 | 	 *
631 | 	 * @param  {HTMLElement} source
632 | 	 * @param  {HTMLElement} target
633 | 	 * @return {void}
634 | 	 */
635 | 	var unproxy = function unproxy(source,target) {
636 | 		proxies = proxies.filter(function(p){
637 | 			if (p.source===source && p.target===target) {
638 | 				if (p.sourceTabIndex!==null) source.setAttribute("tabindex",p.sourceTabIndex);
639 | 				else source.removeAttribute("tabindex");
640 | 				return false;
641 | 			}
642 | 			return true;
643 | 		});
644 | 	};
645 | 
646 | 	document.addEventListener("DOMContentLoaded",function(){
647 | 		document.addEventListener("focus",function(event){
648 | 			var target = event.target;
649 | 			if (event.composedPath) {
650 | 				var path = event.composedPath();
651 | 				if (path.length>0) target = path[0];
652 | 			}
653 | 
654 | 			currentFocus = target;
655 | 
656 | 			var trap = traps[0] || null;
657 | 			if (trap) trap.last = target;
658 | 
659 | 			history.unshift(target);
660 | 			if (historyLimit>-1) history = history.slice(0,historyLimit);
661 | 
662 | 			for (var i=0;i<proxies.length;i++) {
663 | 				var p = proxies[i];
664 | 				if (p.source===target) {
665 | 					focus(p.target);
666 | 					return;
667 | 				}
668 | 			}
669 | 		},true);
670 | 		document.addEventListener("blur",function(event){
671 | 			var target = event.target;
672 | 			if (event.composedPath) {
673 | 				var path = event.composedPath();
674 | 				if (path.length>0) target = path[0];
675 | 			}
676 | 
677 | 			var related = event.relatedTarget;
678 | 			if (related) {
679 | 				var trap = traps[0] || null;
680 | 				if (trap && trap.last) {
681 | 					var anc = DT.ancestors(related,true);
682 | 
683 | 					let found = trap.containers.reduce(function(found,c){
684 | 						if (found) return found;
685 | 						if (anc.indexOf(c)>-1) return true;
686 | 						return false;
687 | 					},false);
688 | 
689 | 					if (!found) focus(trap.last);
690 | 				}
691 | 			}
692 | 
693 | 			previousFocus = target;
694 | 		},true);
695 | 		document.addEventListener("keyup",function(event){
696 | 			if (event.shiftKey && event.keyCode===9) {
697 | 				var source = currentFocus;
698 | 				for (var i=0;i<proxies.length;i++) {
699 | 					var p = proxies[i];
700 | 					if (p.source===source || p.target===source) {
701 | 						focus(previous(p.source));
702 | 						event.preventDefault();
703 | 						return;
704 | 					}
705 | 				}
706 | 			}
707 | 		},true);
708 | 	});
709 | 
710 | 	window.focusManager = {
711 | 		isFocusable: isFocusable,
712 | 		focus: focus,
713 | 		hasFocus: hasFocus,
714 | 		list: list,
715 | 		first: first,
716 | 		last: last,
717 | 		parent: parent,
718 | 		child: child,
719 | 		forward: forward,
720 | 		backward: backward,
721 | 		next: next,
722 | 		previous: previous,
723 | 		trap: trap,
724 | 		untrap: untrap,
725 | 		order: order,
726 | 		proxy: proxy,
727 | 		unproxy: unproxy
728 | 	};
729 | 	Object.defineProperty(window.focusManager,"currentlyFocused",{
730 | 		get: function() {
731 | 			return currentFocus;
732 | 		}
733 | 	});
734 | 	Object.defineProperty(window.focusManager,"previouslyFocused",{
735 | 		get: function() {
736 | 			return previousFocus || null;
737 | 		}
738 | 	});
739 | 	Object.defineProperty(window.focusManager,"history",{
740 | 		get: function() {
741 | 			return [].concat(history);
742 | 		}
743 | 	});
744 | 	Object.defineProperty(window.focusManager,"historyLimit",{
745 | 		get: function() {
746 | 			return historyLimit;
747 | 		},
748 | 		set: function(n) {
749 | 			n = parseInt(n);
750 | 			if (isNaN(n)) return;
751 | 			if (n<-1) return;
752 | 			historyLimit = n;
753 | 
754 | 			if (historyLimit>-1) history = history.slice(0,historyLimit);
755 | 		}
756 | 	});
757 | })();
758 | 


--------------------------------------------------------------------------------