diff --git a/CHANGELOG.md b/CHANGELOG.md index ac228226..80477a34 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ * refactoring all unit and functional tests to use [BDD interface](https://theintern.github.io/intern/#interface-tdd) to improve clarity of a test's intent * fixing [`ally.maintain.tabFocus`][ally/maintain|tab-focus] to also work with Option Tab in Safari for macOS - [issue #146](https://github.com/medialize/ally.js/issues/146) * refactoring `element.prototype.matches` to `util/matches-element` +* adding [`ally.get.activeElement`][ally/get/active-element] - [issue #119](https://github.com/medialize/ally.js/issues/119) ## 1.2.0 - Adios DOMTokenList @@ -325,6 +326,7 @@ Version `1.0.0` is a complete rewrite from the the early `0.0.x` releases, there [ally/fix/pointer-focus-children]: http://allyjs.io/api/fix/pointer-focus-children.html [ally/fix/pointer-focus-input]: http://allyjs.io/api/fix/pointer-focus-input.html [ally/fix/pointer-focus-parent]: http://allyjs.io/api/fix/pointer-focus-parent.html +[ally/get/active-element]: http://allyjs.io/api/get/active-element.html [ally/get/active-elements]: http://allyjs.io/api/get/active-elements.html [ally/get/focus-target]: http://allyjs.io/api/get/focus-target.html [ally/get/focus-redirect-target]: http://allyjs.io/api/get/focus-redirect-target.html diff --git a/docs/api/README.md b/docs/api/README.md index 0d7e632c..6288ac0a 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -83,6 +83,7 @@ Especially when dealing with transitional user interfaces we need to know when a Sometimes you need some DOM traversal utilities * [`ally.get.insignificantBranches`](get/insignificant-branches.md) returns an array containing the branches of the DOM that do contain any of the target elements +* [`ally.get.activeElement`](get/active-element.md) identifies the element that has focus ## Values diff --git a/docs/api/get/active-element.md b/docs/api/get/active-element.md new file mode 100644 index 00000000..ae162fce --- /dev/null +++ b/docs/api/get/active-element.md @@ -0,0 +1,57 @@ +--- +layout: doc-api.html +tags: shadow-dom +--- + +# ally.get.activeElement + +Identifies the element that currently has focus + + +## Description + +This utility is a safeguard for `document.activeElement` presenting invalid references. + + +## Usage + +```js +var element = ally.get.activeElement(); + +var iframeElement = ally.get.activeElement({ + context: iframeDocument, +}); +``` + +### Arguments + + +### Returns + +[`HTMLElement`](https://developer.mozilla.org/en/docs/Web/API/HTMLElement). + +### Throws + + +## Examples + + +## Changes + +* Added in `v#master`. + + +## Notes + + +## Related resources + +* [`ally.get.activeElements`](active-elements.md) + + +## Contributing + +* [module source](https://github.com/medialize/ally.js/blob/master/src/get/active-element.js) +* [document source](https://github.com/medialize/ally.js/blob/master/docs/api/get/active-element.md) +* [unit test](https://github.com/medialize/ally.js/blob/master/test/unit/get.active-element.test.js) + diff --git a/docs/api/get/active-elements.md b/docs/api/get/active-elements.md index f831f24a..9d2662bd 100644 --- a/docs/api/get/active-elements.md +++ b/docs/api/get/active-elements.md @@ -35,6 +35,7 @@ Array of [`HTMLElement`](https://developer.mozilla.org/en/docs/Web/API/HTMLEleme ## Related resources +* [`ally.get.activeElements`](active-elements.md) * [`ally.get.shadowHostParents`](shadow-host-parents.md) is used to identify an elements `ShadowHost` ancestry diff --git a/src/get/_get.js b/src/get/_get.js index 75938bc9..02758013 100644 --- a/src/get/_get.js +++ b/src/get/_get.js @@ -1,6 +1,7 @@ // exporting modules to be included the UMD bundle +import activeElement from './active-element'; import activeElements from './active-elements'; import focusRedirectTarget from './focus-redirect-target'; import focusTarget from './focus-target'; @@ -9,6 +10,7 @@ import parents from './parents'; import shadowHostParents from './shadow-host-parents'; import shadowHost from './shadow-host'; export default { + activeElement, activeElements, focusRedirectTarget, focusTarget, diff --git a/src/get/active-element.js b/src/get/active-element.js new file mode 100644 index 00000000..df4d6998 --- /dev/null +++ b/src/get/active-element.js @@ -0,0 +1,32 @@ + +/* + create ally.get.activeElement() + wrapping ally.get.activeElements() + + fix ally.get.activeElements() + https://github.com/jquery/jquery-ui/blob/ffcfb85c9818954adda69e73cf9ba76ea07b554c/ui/safe-active-element.js +*/ + +import getDocument from '../util/get-document'; + +export default function({ context } = {}) { + const _document = getDocument(context); + let activeElement; + + try { + // IE9 throws an "Unspecified error" accessing document.activeElement from an