https://github.com/tolemac/tolefocus
Framework Agnostic Focus Manager
https://github.com/tolemac/tolefocus
autofocus focus javascript manager mutation-observer typescript
Last synced: about 1 month ago
JSON representation
Framework Agnostic Focus Manager
- Host: GitHub
- URL: https://github.com/tolemac/tolefocus
- Owner: tolemac
- Created: 2017-01-12T23:59:47.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-05-19T06:33:01.000Z (about 9 years ago)
- Last Synced: 2025-02-16T00:05:47.212Z (over 1 year ago)
- Topics: autofocus, focus, javascript, manager, mutation-observer, typescript
- Language: TypeScript
- Homepage:
- Size: 45.9 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# ToleFocus
[](http://badge.fury.io/js/tolefocus) [](https://david-dm.org/tolemac/tolefocus) [](https://david-dm.org/tolemac/tolefocus#info=devDependencies)
> JavaScript Framework agnostic Focus Manager coded in TypeScript
ToleFocus is a small library to manage focus on JavaScript web applications. ToleFocus use ES6 methods, like `array.findIndex`, and require some polyfill like [core-js](https://github.com/zloirock/core-js) in order to work in old browsers, like IE.
ToleFocus is highly inspired on [Angular Focus Manager](https://github.com/obogo/angular-focusmanager) coded by [Rob Tylor](https://github.com/roboncode).
## Installation
````
npm install tolefocus --save
````
## Usage
To enable the focus manager you have to import `focusManager` from `tolefocus` module and call `enable` method.
```` javascript
import {focusManager} from "tolefocus";
focusManager.enable();
````
This load the content of `body` tag searching for ToleFocus attributes.
You can enable the built in DOM observer witch use [MutationObserver](https://developer.mozilla.org/es/docs/Web/API/MutationObserver) in order to detect the DOM changes.
```` javascript
import {focusManager, focusObserver} from "tolefocus";
focusManager.enable();
focusObserver.enable();
````
ToleFocus handles by default the TAB key in the common focusables controls and sends focus to the next or previous control.
### Setting focus order
You can set the focus order:
```` html
````
Focus order is zero based, you can set negative focus order to any element, the negative focus order are pushed to the first positions.
```` html
````
### Focus groups
You can create focus groups where each element can to have his own focus-order in the group.
```` html
````
### Focus loopback control
You can control the group loopback, you can set the head and tail behaivor. When behaivor is "stop" the focus doesn't go to the next element, the foucus stops in the last or first element. When behaivor is "loop" the focus go from last to first element in the group or from the first to the end element.
```` html
````
### Non-selectable elements
You can send focus to other controls like `div` or `spans`, you have to set `focus-order` attribute.
```` html
````
### Autofocus
You can set an element as autofocus to set focus on it automatically. If you have the `focusObserver` enabled the element will focus when it's added to the DOM.
```` html
````
If you want to hide a element and get focused when it becomes visible you can set `observe` value to `autofocus` attribute.
```` html
Show
````
### Custom focusable elements
You can add selectors to handle focusable elements, for example you can add elements with class `select2-selection` as focusable elements, then `tolefocus` detect this elements as focusables.
````javascript
focusManager.addCustomSelector(".select2-selection");
````
### Decide if element can get the focus
When `tolefocus` going to set focus to an element, it ask if the element can get focus, by default it look if element is visible and not disabled this way:
````javascript
const visible = element.offsetParent !== null;
const disable = !!element["disabled"];
return visible && !disable;
````
You can set a handler to decide if element can get focus, for example you can do that elements with class `select2-hidden-accessible` don't get the focus:
````javascript
focusManager.setCanElementGetFocusHandler((element) => {
if (element.classList.contains("select2-hidden-accessible")) {
return false;
}
});
````
If handler don't return a value `tolefocus` decide via `visible` and `disabled`.
#### Select2 support
`Select2` hide the `` element and redirect focus to a self created ``, `tolefocus` can't detect this behivor without help, you have to mark the `span` as focusable and disable the select to get focus, you can do it this way:
````javascript
// Select2 Focus management.
focusManager.addCustomSelector(".select2-selection");
focusManager.setCanElementGetFocusHandler((element) => {
if (element.classList.contains("select2-hidden-accessible")) {
return false;
}
});
// end select2 Focus management
// Enable tolefocus.
focusManager.enable();
focusObserver.enable();
````
## SystemJS config
To use using SystemJS you have to map tolefocus to the distributed bundle:
```` javascript
System.config({
...
...
map: {
tolefocus: './node_modules/tolefocus/dist/bundles/tolefocus.bundle.umd.js'
...
...
},
...
...
})
````
## Build
Pull request are welcome, to build it:
````
git clone https://github.com/tolemac/tolefocus.git
cd tolefocus
npm install
npm run build
````
You can launch test suite using:
````
npm run test
````