focus-lock - npm Package Compare versions

Comparing version 0.11.6 to 1.0.0

dist/es2015/focusables.d.ts

@@ -1,5 +0,5 @@
-interface FocusableIn {
+interface FocusableNode {
     node: HTMLElement;
     /**
-     * tab index
+     * index in the tab order
      */
@@ -17,10 +17,6 @@ index: number;
 /**
- * return list of focusable elements inside a given top node
- * @deprecated use {@link getFocusableIn}. Yep, there is typo in the function name
+ * @returns list of focusable elements inside a given top node
+ * @see {@link getFocusableNodes} for lower level access
  */
-export declare const getFocusabledIn: (topNode: HTMLElement) => FocusableIn[];
-/**
- * return list of focusable elements inside a given top node
- */
-export declare const getFocusableIn: (topNode: HTMLElement) => FocusableIn[];
+export declare const expandFocusableNodes: (topNode: HTMLElement) => FocusableNode[];
 export {};

dist/es2015/focusables.js

@@ -6,6 +6,6 @@ import { getTabbableNodes } from './utils/DOMutils';
 /**
- * return list of focusable elements inside a given top node
- * @deprecated use {@link getFocusableIn}. Yep, there is typo in the function name
+ * @returns list of focusable elements inside a given top node
+ * @see {@link getFocusableNodes} for lower level access
  */
-export var getFocusabledIn = function (topNode) {
+export var expandFocusableNodes = function (topNode) {
     var entries = getAllAffectedNodes(topNode).filter(isNotAGuard);
@@ -34,5 +34,1 @@ var commonParent = getTopCommonParent(topNode, topNode, entries);
 };
-/**
- * return list of focusable elements inside a given top node
- */
-export var getFocusableIn = getFocusabledIn;

dist/es2015/focusInside.d.ts

 /**
- * @returns {Boolean} true, if the current focus is inside given node or nodes
+ * @returns {Boolean} true, if the current focus is inside given node or nodes.
+ * Supports nodes hidden inside shadowDom
  */
 export declare const focusInside: (topNode: HTMLElement | HTMLElement[], activeElement?: HTMLElement | undefined) => boolean;

dist/es2015/focusInside.js

@@ -10,3 +10,4 @@ import { contains } from './utils/DOMutils';
 /**
- * @returns {Boolean} true, if the current focus is inside given node or nodes
+ * @returns {Boolean} true, if the current focus is inside given node or nodes.
+ * Supports nodes hidden inside shadowDom
  */
@@ -13,0 +14,0 @@ export var focusInside = function (topNode, activeElement) {

dist/es2015/focusIsHidden.d.ts

 /**
- * focus is hidden FROM the focus-lock
+ * checks if focus is hidden FROM the focus-lock
  * ie contained inside a node focus-lock shall ignore
+ *
+ * This is a utility function coupled with {@link FOCUS_ALLOW} constant
+ *
  * @returns {boolean} focus is currently is in "allow" area
  */
 export declare const focusIsHidden: (inDocument?: Document) => boolean;

dist/es2015/focusIsHidden.js

@@ -6,4 +6,7 @@ import { FOCUS_ALLOW } from './constants';
 /**
- * focus is hidden FROM the focus-lock
+ * checks if focus is hidden FROM the focus-lock
  * ie contained inside a node focus-lock shall ignore
+ *
+ * This is a utility function coupled with {@link FOCUS_ALLOW} constant
+ *
  * @returns {boolean} focus is currently is in "allow" area
@@ -10,0 +13,0 @@ */

dist/es2015/focusMerge.d.ts

 /**
- * given top node(s) and the last active element return the element to be focused next
+ * The main functionality of the focus-lock package
+ *
+ * given top node(s) and the last active element returns the element to be focused next
+ * @returns element which should be focused to move focus inside
  * @param topNode
  * @param lastNode
  */
-export declare const getFocusMerge: (topNode: Element | Element[], lastNode: Element | null) => undefined | {
+export declare const focusMerge: (topNode: Element | Element[], lastNode: Element | null) => undefined | {
     node: HTMLElement;
 };

dist/es2015/focusMerge.js

@@ -17,7 +17,10 @@ import { NEW_FOCUS, newFocus } from './solver';
 /**
- * given top node(s) and the last active element return the element to be focused next
+ * The main functionality of the focus-lock package
+ *
+ * given top node(s) and the last active element returns the element to be focused next
+ * @returns element which should be focused to move focus inside
  * @param topNode
  * @param lastNode
  */
-export var getFocusMerge = function (topNode, lastNode) {
+export var focusMerge = function (topNode, lastNode) {
     var activeElement = getActiveElement(asArray(topNode).length > 0 ? document : getFirst(topNode).ownerDocument);
@@ -24,0 +27,0 @@ var entries = getAllAffectedNodes(topNode).filter(isNotAGuard);

dist/es2015/index.d.ts

@@ -1,12 +0,19 @@
-import * as constants from './constants';
+import * as allConstants from './constants';
 import { focusInside } from './focusInside';
 import { focusIsHidden } from './focusIsHidden';
-import { getFocusMerge as focusMerge } from './focusMerge';
-import { getFocusabledIn, getFocusableIn } from './focusables';
-import { setFocus } from './setFocus';
-import { focusNextElement, focusPrevElement } from './sibling';
-import tabHook from './tabHook';
-import { getAllAffectedNodes } from './utils/all-affected';
-import { getActiveElement } from './utils/getActiveElement';
-export { tabHook, focusInside, focusIsHidden, focusMerge, getFocusableIn, getFocusabledIn, constants, getAllAffectedNodes, focusNextElement, focusPrevElement, getActiveElement, };
-export default setFocus;
+import { focusSolver } from './focusSolver';
+import { expandFocusableNodes } from './focusables';
+import { moveFocusInside } from './moveFocusInside';
+import { focusNextElement, focusPrevElement, getRelativeFocusable } from './sibling';
+import { getFocusableNodes, getTabbableNodes } from './utils/DOMutils';
+/**
+ * magic symbols to control focus behavior from DOM
+ * see description of every particular one
+ */
+declare const constants: typeof allConstants;
+export { constants, focusInside, focusIsHidden, moveFocusInside, focusSolver, expandFocusableNodes, getFocusableNodes, getTabbableNodes, focusNextElement, focusPrevElement, getRelativeFocusable, };
+/**
+ * @deprecated - please use {@link moveFocusInside} named export
+ */
+declare const deprecated_default_moveFocusInside: typeof moveFocusInside;
+export default deprecated_default_moveFocusInside;

dist/es2015/index.js

@@ -1,13 +0,28 @@
-import * as constants from './constants';
+import * as allConstants from './constants';
 import { focusInside } from './focusInside';
 import { focusIsHidden } from './focusIsHidden';
-import { getFocusMerge as focusMerge } from './focusMerge';
-import { getFocusabledIn, getFocusableIn } from './focusables';
-import { setFocus } from './setFocus';
-import { focusNextElement, focusPrevElement } from './sibling';
-import tabHook from './tabHook';
-import { getAllAffectedNodes } from './utils/all-affected';
-import { getActiveElement } from './utils/getActiveElement';
-export { tabHook, focusInside, focusIsHidden, focusMerge, getFocusableIn, getFocusabledIn, constants, getAllAffectedNodes, focusNextElement, focusPrevElement, getActiveElement, };
-export default setFocus;
+import { focusSolver } from './focusSolver';
+import { expandFocusableNodes } from './focusables';
+import { moveFocusInside } from './moveFocusInside';
+import { focusNextElement, focusPrevElement, getRelativeFocusable } from './sibling';
+import { getFocusableNodes, getTabbableNodes } from './utils/DOMutils';
+/**
+ * magic symbols to control focus behavior from DOM
+ * see description of every particular one
+ */
+var constants = allConstants;
+export { constants, 
 //
+focusInside, focusIsHidden, 
+//
+moveFocusInside, focusSolver, 
+//
+expandFocusableNodes, getFocusableNodes, getTabbableNodes, 
+//
+focusNextElement, focusPrevElement, getRelativeFocusable, };
+/**
+ * @deprecated - please use {@link moveFocusInside} named export
+ */
+var deprecated_default_moveFocusInside = moveFocusInside;
+export default deprecated_default_moveFocusInside;
+//

dist/es2015/setFocus.d.ts

@@ -6,9 +6,10 @@ export declare const focusOn: (target: Element | HTMLFrameElement | HTMLElement, focusOptions?: FocusOptions | undefined) => void;
 /**
- * Sets focus at a given node. The last focused element will help to determine which element(first or last) should be focused.
+ * Control focus at a given node.
+ * The last focused element will help to determine which element(first or last) should be focused.
+ *
+ * In principle is nothing more than a wrapper around {@link focusMerge} with autofocus
+ *
  * HTML markers (see {@link import('./constants').FOCUS_AUTO} constants) can control autofocus
- * @param topNode
- * @param lastNode
- * @param options
  */
 export declare const setFocus: (topNode: HTMLElement, lastNode: Element, options?: FocusLockFocusOptions) => void;
 export {};

dist/es2015/setFocus.js

@@ -1,2 +0,2 @@
-import { getFocusMerge } from './focusMerge';
+import { focusMerge } from './focusMerge';
 export var focusOn = function (target, focusOptions) {
@@ -13,11 +13,12 @@ if ('focus' in target) {
 /**
- * Sets focus at a given node. The last focused element will help to determine which element(first or last) should be focused.
+ * Control focus at a given node.
+ * The last focused element will help to determine which element(first or last) should be focused.
+ *
+ * In principle is nothing more than a wrapper around {@link focusMerge} with autofocus
+ *
  * HTML markers (see {@link import('./constants').FOCUS_AUTO} constants) can control autofocus
- * @param topNode
- * @param lastNode
- * @param options
  */
 export var setFocus = function (topNode, lastNode, options) {
     if (options === void 0) { options = {}; }
-    var focusable = getFocusMerge(topNode, lastNode);
+    var focusable = focusMerge(topNode, lastNode);
     if (lockDisabled) {
@@ -24,0 +25,0 @@ return;

dist/es2015/sibling.d.ts

@@ -0,1 +1,19 @@
+/**
+ * for a given `element` in a given `scope` returns focusable siblings
+ * @param element - base element
+ * @param scope - common parent. Can be document, but better to narrow it down for performance reasons
+ * @returns {prev,next} - references to a focusable element before and after
+ * @returns undefined - if operation is not applicable
+ */
+export declare const getRelativeFocusable: (element: Element, scope: HTMLElement | Document) => {
+    prev?: undefined;
+    next?: undefined;
+    first?: undefined;
+    last?: undefined;
+} | {
+    prev: import("./utils/tabOrder").NodeIndex;
+    next: import("./utils/tabOrder").NodeIndex;
+    first: import("./utils/tabOrder").NodeIndex;
+    last: import("./utils/tabOrder").NodeIndex;
+} | undefined;
 interface FocusNextOptions {
@@ -19,12 +37,12 @@ /**
  * focuses next element in the tab-order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export declare const focusNextElement: (baseElement: Element, options?: FocusNextOptions) => void;
+export declare const focusNextElement: (fromElement: Element, options?: FocusNextOptions) => void;
 /**
  * focuses prev element in the tab order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export declare const focusPrevElement: (baseElement: Element, options?: FocusNextOptions) => void;
+export declare const focusPrevElement: (fromElement: Element, options?: FocusNextOptions) => void;
 export {};

dist/es2015/sibling.js

@@ -1,4 +0,11 @@
-import { focusOn } from './setFocus';
+import { focusOn } from './commands';
 import { getTabbableNodes, contains } from './utils/DOMutils';
-var getRelativeFocusable = function (element, scope) {
+/**
+ * for a given `element` in a given `scope` returns focusable siblings
+ * @param element - base element
+ * @param scope - common parent. Can be document, but better to narrow it down for performance reasons
+ * @returns {prev,next} - references to a focusable element before and after
+ * @returns undefined - if operation is not applicable
+ */
+export var getRelativeFocusable = function (element, scope) {
     if (!element || !scope || !contains(scope, element)) {
@@ -13,3 +20,4 @@ return {};
     if (current === -1) {
-        return {};
+        // an edge case, when anchor element is not found
+        return undefined;
     }
@@ -31,9 +39,13 @@ return {
  * focuses next element in the tab-order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export var focusNextElement = function (baseElement, options) {
+export var focusNextElement = function (fromElement, options) {
     if (options === void 0) { options = {}; }
     var _a = defaultOptions(options), scope = _a.scope, cycle = _a.cycle;
-    var _b = getRelativeFocusable(baseElement, scope), next = _b.next, first = _b.first;
+    var solution = getRelativeFocusable(fromElement, scope);
+    if (!solution) {
+        return;
+    }
+    var next = solution.next, first = solution.first;
     var newTarget = next || (cycle && first);
@@ -46,9 +58,13 @@ if (newTarget) {
  * focuses prev element in the tab order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export var focusPrevElement = function (baseElement, options) {
+export var focusPrevElement = function (fromElement, options) {
     if (options === void 0) { options = {}; }
     var _a = defaultOptions(options), scope = _a.scope, cycle = _a.cycle;
-    var _b = getRelativeFocusable(baseElement, scope), prev = _b.prev, last = _b.last;
+    var solution = getRelativeFocusable(fromElement, scope);
+    if (!solution) {
+        return;
+    }
+    var prev = solution.prev, last = solution.last;
     var newTarget = prev || (cycle && last);
@@ -55,0 +71,0 @@ if (newTarget) {

dist/es2015/utils/all-affected.d.ts

 /**
  * returns all "focus containers" inside a given node
- * @param node
- * @returns {T}
+ * @param node - node or nodes to look inside
+ * @returns Element[]
  */
 export declare const getAllAffectedNodes: (node: Element | Element[]) => Element[];

dist/es2015/utils/all-affected.js

@@ -38,4 +38,4 @@ import { FOCUS_DISABLED, FOCUS_GROUP } from '../constants';
  * returns all "focus containers" inside a given node
- * @param node
- * @returns {T}
+ * @param node - node or nodes to look inside
+ * @returns Element[]
  */
@@ -42,0 +42,0 @@ export var getAllAffectedNodes = function (node) {

dist/es2015/utils/DOMutils.d.ts

@@ -11,11 +11,23 @@ import { VisibilityCache } from './is';
 /**
- * only tabbable ones
- * (but with guards which would be ignored)
+ * !__WARNING__! Low level API.
+ * @returns all tabbable nodes
+ *
+ * @see {@link getFocusableNodes} to get any focusable element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
 export declare const getTabbableNodes: (topNodes: Element[], visibilityCache: VisibilityCache, withGuards?: boolean | undefined) => NodeIndex[];
 /**
- * actually anything "focusable", not only tabbable
- * (without guards, as long as they are not expected to be focused)
+ * !__WARNING__! Low level API.
+ *
+ * @returns anything "focusable", not only tabbable. The difference is in `tabIndex=-1`
+ * (without guards, as long as they are not expected to be ever focused)
+ *
+ * @see {@link getTabbableNodes} to get only tabble nodes element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
-export declare const getAllTabbableNodes: (topNodes: Element[], visibilityCache: VisibilityCache) => NodeIndex[];
+export declare const getFocusableNodes: (topNodes: Element[], visibilityCache: VisibilityCache) => NodeIndex[];
 /**
@@ -22,0 +34,0 @@ * return list of nodes which are expected to be auto-focused

dist/es2015/utils/DOMutils.js

@@ -20,4 +20,9 @@ import { toArray } from './array';
 /**
- * only tabbable ones
- * (but with guards which would be ignored)
+ * !__WARNING__! Low level API.
+ * @returns all tabbable nodes
+ *
+ * @see {@link getFocusableNodes} to get any focusable element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
@@ -28,6 +33,13 @@ export var getTabbableNodes = function (topNodes, visibilityCache, withGuards) {
 /**
- * actually anything "focusable", not only tabbable
- * (without guards, as long as they are not expected to be focused)
+ * !__WARNING__! Low level API.
+ *
+ * @returns anything "focusable", not only tabbable. The difference is in `tabIndex=-1`
+ * (without guards, as long as they are not expected to be ever focused)
+ *
+ * @see {@link getTabbableNodes} to get only tabble nodes element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
-export var getAllTabbableNodes = function (topNodes, visibilityCache) {
+export var getFocusableNodes = function (topNodes, visibilityCache) {
     return orderByTabIndex(filterFocusable(getFocusables(topNodes), visibilityCache), false);
@@ -34,0 +46,0 @@ };

dist/es2015/utils/getActiveElement.d.ts

@@ -0,1 +1,5 @@
+/**
+ * returns current active element. If the active element is a "container" itself(shadowRoot or iframe) returns active element inside it
+ * @param [inDocument]
+ */
 export declare const getActiveElement: (inDocument?: Document | ShadowRoot | undefined) => HTMLElement | undefined;

dist/es2015/utils/getActiveElement.js

@@ -5,2 +5,6 @@ /**
 import { safeProbe } from './safe';
+/**
+ * returns current active element. If the active element is a "container" itself(shadowRoot or iframe) returns active element inside it
+ * @param [inDocument]
+ */
 export var getActiveElement = function (inDocument) {
@@ -7,0 +11,0 @@ if (inDocument === void 0) { inDocument = document; }

dist/es2019/focusables.d.ts

@@ -1,5 +0,5 @@
-interface FocusableIn {
+interface FocusableNode {
     node: HTMLElement;
     /**
-     * tab index
+     * index in the tab order
      */
@@ -17,10 +17,6 @@ index: number;
 /**
- * return list of focusable elements inside a given top node
- * @deprecated use {@link getFocusableIn}. Yep, there is typo in the function name
+ * @returns list of focusable elements inside a given top node
+ * @see {@link getFocusableNodes} for lower level access
  */
-export declare const getFocusabledIn: (topNode: HTMLElement) => FocusableIn[];
-/**
- * return list of focusable elements inside a given top node
- */
-export declare const getFocusableIn: (topNode: HTMLElement) => FocusableIn[];
+export declare const expandFocusableNodes: (topNode: HTMLElement) => FocusableNode[];
 export {};

dist/es2019/focusables.js

@@ -6,6 +6,6 @@ import { getTabbableNodes } from './utils/DOMutils';
 /**
- * return list of focusable elements inside a given top node
- * @deprecated use {@link getFocusableIn}. Yep, there is typo in the function name
+ * @returns list of focusable elements inside a given top node
+ * @see {@link getFocusableNodes} for lower level access
  */
-export const getFocusabledIn = (topNode) => {
+export const expandFocusableNodes = (topNode) => {
     const entries = getAllAffectedNodes(topNode).filter(isNotAGuard);
@@ -25,5 +25,1 @@ const commonParent = getTopCommonParent(topNode, topNode, entries);
 };
-/**
- * return list of focusable elements inside a given top node
- */
-export const getFocusableIn = getFocusabledIn;

dist/es2019/focusInside.d.ts

 /**
- * @returns {Boolean} true, if the current focus is inside given node or nodes
+ * @returns {Boolean} true, if the current focus is inside given node or nodes.
+ * Supports nodes hidden inside shadowDom
  */
 export declare const focusInside: (topNode: HTMLElement | HTMLElement[], activeElement?: HTMLElement | undefined) => boolean;

dist/es2019/focusInside.js

@@ -8,3 +8,4 @@ import { contains } from './utils/DOMutils';
 /**
- * @returns {Boolean} true, if the current focus is inside given node or nodes
+ * @returns {Boolean} true, if the current focus is inside given node or nodes.
+ * Supports nodes hidden inside shadowDom
  */
@@ -11,0 +12,0 @@ export const focusInside = (topNode, activeElement = getActiveElement(getFirst(topNode).ownerDocument)) => {

dist/es2019/focusIsHidden.d.ts

 /**
- * focus is hidden FROM the focus-lock
+ * checks if focus is hidden FROM the focus-lock
  * ie contained inside a node focus-lock shall ignore
+ *
+ * This is a utility function coupled with {@link FOCUS_ALLOW} constant
+ *
  * @returns {boolean} focus is currently is in "allow" area
  */
 export declare const focusIsHidden: (inDocument?: Document) => boolean;

dist/es2019/focusIsHidden.js

@@ -6,4 +6,7 @@ import { FOCUS_ALLOW } from './constants';
 /**
- * focus is hidden FROM the focus-lock
+ * checks if focus is hidden FROM the focus-lock
  * ie contained inside a node focus-lock shall ignore
+ *
+ * This is a utility function coupled with {@link FOCUS_ALLOW} constant
+ *
  * @returns {boolean} focus is currently is in "allow" area
@@ -10,0 +13,0 @@ */

dist/es2019/focusMerge.d.ts

 /**
- * given top node(s) and the last active element return the element to be focused next
+ * The main functionality of the focus-lock package
+ *
+ * given top node(s) and the last active element returns the element to be focused next
+ * @returns element which should be focused to move focus inside
  * @param topNode
  * @param lastNode
  */
-export declare const getFocusMerge: (topNode: Element | Element[], lastNode: Element | null) => undefined | {
+export declare const focusMerge: (topNode: Element | Element[], lastNode: Element | null) => undefined | {
     node: HTMLElement;
 };

dist/es2019/focusMerge.js

@@ -17,7 +17,10 @@ import { NEW_FOCUS, newFocus } from './solver';
 /**
- * given top node(s) and the last active element return the element to be focused next
+ * The main functionality of the focus-lock package
+ *
+ * given top node(s) and the last active element returns the element to be focused next
+ * @returns element which should be focused to move focus inside
  * @param topNode
  * @param lastNode
  */
-export const getFocusMerge = (topNode, lastNode) => {
+export const focusMerge = (topNode, lastNode) => {
     const activeElement = getActiveElement(asArray(topNode).length > 0 ? document : getFirst(topNode).ownerDocument);
@@ -24,0 +27,0 @@ const entries = getAllAffectedNodes(topNode).filter(isNotAGuard);

dist/es2019/index.d.ts

@@ -1,12 +0,19 @@
-import * as constants from './constants';
+import * as allConstants from './constants';
 import { focusInside } from './focusInside';
 import { focusIsHidden } from './focusIsHidden';
-import { getFocusMerge as focusMerge } from './focusMerge';
-import { getFocusabledIn, getFocusableIn } from './focusables';
-import { setFocus } from './setFocus';
-import { focusNextElement, focusPrevElement } from './sibling';
-import tabHook from './tabHook';
-import { getAllAffectedNodes } from './utils/all-affected';
-import { getActiveElement } from './utils/getActiveElement';
-export { tabHook, focusInside, focusIsHidden, focusMerge, getFocusableIn, getFocusabledIn, constants, getAllAffectedNodes, focusNextElement, focusPrevElement, getActiveElement, };
-export default setFocus;
+import { focusSolver } from './focusSolver';
+import { expandFocusableNodes } from './focusables';
+import { moveFocusInside } from './moveFocusInside';
+import { focusNextElement, focusPrevElement, getRelativeFocusable } from './sibling';
+import { getFocusableNodes, getTabbableNodes } from './utils/DOMutils';
+/**
+ * magic symbols to control focus behavior from DOM
+ * see description of every particular one
+ */
+declare const constants: typeof allConstants;
+export { constants, focusInside, focusIsHidden, moveFocusInside, focusSolver, expandFocusableNodes, getFocusableNodes, getTabbableNodes, focusNextElement, focusPrevElement, getRelativeFocusable, };
+/**
+ * @deprecated - please use {@link moveFocusInside} named export
+ */
+declare const deprecated_default_moveFocusInside: typeof moveFocusInside;
+export default deprecated_default_moveFocusInside;

dist/es2019/index.js

@@ -1,13 +0,28 @@
-import * as constants from './constants';
+import * as allConstants from './constants';
 import { focusInside } from './focusInside';
 import { focusIsHidden } from './focusIsHidden';
-import { getFocusMerge as focusMerge } from './focusMerge';
-import { getFocusabledIn, getFocusableIn } from './focusables';
-import { setFocus } from './setFocus';
-import { focusNextElement, focusPrevElement } from './sibling';
-import tabHook from './tabHook';
-import { getAllAffectedNodes } from './utils/all-affected';
-import { getActiveElement } from './utils/getActiveElement';
-export { tabHook, focusInside, focusIsHidden, focusMerge, getFocusableIn, getFocusabledIn, constants, getAllAffectedNodes, focusNextElement, focusPrevElement, getActiveElement, };
-export default setFocus;
+import { focusSolver } from './focusSolver';
+import { expandFocusableNodes } from './focusables';
+import { moveFocusInside } from './moveFocusInside';
+import { focusNextElement, focusPrevElement, getRelativeFocusable } from './sibling';
+import { getFocusableNodes, getTabbableNodes } from './utils/DOMutils';
+/**
+ * magic symbols to control focus behavior from DOM
+ * see description of every particular one
+ */
+const constants = allConstants;
+export { constants, 
 //
+focusInside, focusIsHidden, 
+//
+moveFocusInside, focusSolver, 
+//
+expandFocusableNodes, getFocusableNodes, getTabbableNodes, 
+//
+focusNextElement, focusPrevElement, getRelativeFocusable, };
+/**
+ * @deprecated - please use {@link moveFocusInside} named export
+ */
+const deprecated_default_moveFocusInside = moveFocusInside;
+export default deprecated_default_moveFocusInside;
+//

dist/es2019/setFocus.d.ts

@@ -6,9 +6,10 @@ export declare const focusOn: (target: Element | HTMLFrameElement | HTMLElement, focusOptions?: FocusOptions | undefined) => void;
 /**
- * Sets focus at a given node. The last focused element will help to determine which element(first or last) should be focused.
+ * Control focus at a given node.
+ * The last focused element will help to determine which element(first or last) should be focused.
+ *
+ * In principle is nothing more than a wrapper around {@link focusMerge} with autofocus
+ *
  * HTML markers (see {@link import('./constants').FOCUS_AUTO} constants) can control autofocus
- * @param topNode
- * @param lastNode
- * @param options
  */
 export declare const setFocus: (topNode: HTMLElement, lastNode: Element, options?: FocusLockFocusOptions) => void;
 export {};

dist/es2019/setFocus.js

@@ -1,2 +0,2 @@
-import { getFocusMerge } from './focusMerge';
+import { focusMerge } from './focusMerge';
 export const focusOn = (target, focusOptions) => {
@@ -13,10 +13,11 @@ if ('focus' in target) {
 /**
- * Sets focus at a given node. The last focused element will help to determine which element(first or last) should be focused.
+ * Control focus at a given node.
+ * The last focused element will help to determine which element(first or last) should be focused.
+ *
+ * In principle is nothing more than a wrapper around {@link focusMerge} with autofocus
+ *
  * HTML markers (see {@link import('./constants').FOCUS_AUTO} constants) can control autofocus
- * @param topNode
- * @param lastNode
- * @param options
  */
 export const setFocus = (topNode, lastNode, options = {}) => {
-    const focusable = getFocusMerge(topNode, lastNode);
+    const focusable = focusMerge(topNode, lastNode);
     if (lockDisabled) {
@@ -23,0 +24,0 @@ return;

dist/es2019/sibling.d.ts

@@ -0,1 +1,19 @@
+/**
+ * for a given `element` in a given `scope` returns focusable siblings
+ * @param element - base element
+ * @param scope - common parent. Can be document, but better to narrow it down for performance reasons
+ * @returns {prev,next} - references to a focusable element before and after
+ * @returns undefined - if operation is not applicable
+ */
+export declare const getRelativeFocusable: (element: Element, scope: HTMLElement | Document) => {
+    prev?: undefined;
+    next?: undefined;
+    first?: undefined;
+    last?: undefined;
+} | {
+    prev: import("./utils/tabOrder").NodeIndex;
+    next: import("./utils/tabOrder").NodeIndex;
+    first: import("./utils/tabOrder").NodeIndex;
+    last: import("./utils/tabOrder").NodeIndex;
+} | undefined;
 interface FocusNextOptions {
@@ -19,12 +37,12 @@ /**
  * focuses next element in the tab-order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export declare const focusNextElement: (baseElement: Element, options?: FocusNextOptions) => void;
+export declare const focusNextElement: (fromElement: Element, options?: FocusNextOptions) => void;
 /**
  * focuses prev element in the tab order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export declare const focusPrevElement: (baseElement: Element, options?: FocusNextOptions) => void;
+export declare const focusPrevElement: (fromElement: Element, options?: FocusNextOptions) => void;
 export {};

dist/es2019/sibling.js

@@ -1,4 +0,11 @@
-import { focusOn } from './setFocus';
+import { focusOn } from './commands';
 import { getTabbableNodes, contains } from './utils/DOMutils';
-const getRelativeFocusable = (element, scope) => {
+/**
+ * for a given `element` in a given `scope` returns focusable siblings
+ * @param element - base element
+ * @param scope - common parent. Can be document, but better to narrow it down for performance reasons
+ * @returns {prev,next} - references to a focusable element before and after
+ * @returns undefined - if operation is not applicable
+ */
+export const getRelativeFocusable = (element, scope) => {
     if (!element || !scope || !contains(scope, element)) {
@@ -10,3 +17,4 @@ return {};
     if (current === -1) {
-        return {};
+        // an edge case, when anchor element is not found
+        return undefined;
     }
@@ -26,8 +34,12 @@ return {
  * focuses next element in the tab-order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export const focusNextElement = (baseElement, options = {}) => {
+export const focusNextElement = (fromElement, options = {}) => {
     const { scope, cycle } = defaultOptions(options);
-    const { next, first } = getRelativeFocusable(baseElement, scope);
+    const solution = getRelativeFocusable(fromElement, scope);
+    if (!solution) {
+        return;
+    }
+    const { next, first } = solution;
     const newTarget = next || (cycle && first);
@@ -40,8 +52,12 @@ if (newTarget) {
  * focuses prev element in the tab order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export const focusPrevElement = (baseElement, options = {}) => {
+export const focusPrevElement = (fromElement, options = {}) => {
     const { scope, cycle } = defaultOptions(options);
-    const { prev, last } = getRelativeFocusable(baseElement, scope);
+    const solution = getRelativeFocusable(fromElement, scope);
+    if (!solution) {
+        return;
+    }
+    const { prev, last } = solution;
     const newTarget = prev || (cycle && last);
@@ -48,0 +64,0 @@ if (newTarget) {

dist/es2019/utils/all-affected.d.ts

 /**
  * returns all "focus containers" inside a given node
- * @param node
- * @returns {T}
+ * @param node - node or nodes to look inside
+ * @returns Element[]
  */
 export declare const getAllAffectedNodes: (node: Element | Element[]) => Element[];

dist/es2019/utils/all-affected.js

@@ -36,4 +36,4 @@ import { FOCUS_DISABLED, FOCUS_GROUP } from '../constants';
  * returns all "focus containers" inside a given node
- * @param node
- * @returns {T}
+ * @param node - node or nodes to look inside
+ * @returns Element[]
  */
@@ -40,0 +40,0 @@ export const getAllAffectedNodes = (node) => {

dist/es2019/utils/DOMutils.d.ts

@@ -11,11 +11,23 @@ import { VisibilityCache } from './is';
 /**
- * only tabbable ones
- * (but with guards which would be ignored)
+ * !__WARNING__! Low level API.
+ * @returns all tabbable nodes
+ *
+ * @see {@link getFocusableNodes} to get any focusable element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
 export declare const getTabbableNodes: (topNodes: Element[], visibilityCache: VisibilityCache, withGuards?: boolean | undefined) => NodeIndex[];
 /**
- * actually anything "focusable", not only tabbable
- * (without guards, as long as they are not expected to be focused)
+ * !__WARNING__! Low level API.
+ *
+ * @returns anything "focusable", not only tabbable. The difference is in `tabIndex=-1`
+ * (without guards, as long as they are not expected to be ever focused)
+ *
+ * @see {@link getTabbableNodes} to get only tabble nodes element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
-export declare const getAllTabbableNodes: (topNodes: Element[], visibilityCache: VisibilityCache) => NodeIndex[];
+export declare const getFocusableNodes: (topNodes: Element[], visibilityCache: VisibilityCache) => NodeIndex[];
 /**
@@ -22,0 +34,0 @@ * return list of nodes which are expected to be auto-focused

dist/es2019/utils/DOMutils.js

@@ -15,11 +15,23 @@ import { toArray } from './array';
 /**
- * only tabbable ones
- * (but with guards which would be ignored)
+ * !__WARNING__! Low level API.
+ * @returns all tabbable nodes
+ *
+ * @see {@link getFocusableNodes} to get any focusable element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
 export const getTabbableNodes = (topNodes, visibilityCache, withGuards) => orderByTabIndex(filterFocusable(getFocusables(topNodes, withGuards), visibilityCache), true, withGuards);
 /**
- * actually anything "focusable", not only tabbable
- * (without guards, as long as they are not expected to be focused)
+ * !__WARNING__! Low level API.
+ *
+ * @returns anything "focusable", not only tabbable. The difference is in `tabIndex=-1`
+ * (without guards, as long as they are not expected to be ever focused)
+ *
+ * @see {@link getTabbableNodes} to get only tabble nodes element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
-export const getAllTabbableNodes = (topNodes, visibilityCache) => orderByTabIndex(filterFocusable(getFocusables(topNodes), visibilityCache), false);
+export const getFocusableNodes = (topNodes, visibilityCache) => orderByTabIndex(filterFocusable(getFocusables(topNodes), visibilityCache), false);
 /**
@@ -26,0 +38,0 @@ * return list of nodes which are expected to be auto-focused

dist/es2019/utils/getActiveElement.d.ts

@@ -0,1 +1,5 @@
+/**
+ * returns current active element. If the active element is a "container" itself(shadowRoot or iframe) returns active element inside it
+ * @param [inDocument]
+ */
 export declare const getActiveElement: (inDocument?: Document | ShadowRoot | undefined) => HTMLElement | undefined;

dist/es2019/utils/getActiveElement.js

@@ -5,2 +5,6 @@ /**
 import { safeProbe } from './safe';
+/**
+ * returns current active element. If the active element is a "container" itself(shadowRoot or iframe) returns active element inside it
+ * @param [inDocument]
+ */
 export const getActiveElement = (inDocument = document) => {
@@ -7,0 +11,0 @@ if (!inDocument || !inDocument.activeElement) {

dist/es5/focusables.d.ts

@@ -1,5 +0,5 @@
-interface FocusableIn {
+interface FocusableNode {
     node: HTMLElement;
     /**
-     * tab index
+     * index in the tab order
      */
@@ -17,10 +17,6 @@ index: number;
 /**
- * return list of focusable elements inside a given top node
- * @deprecated use {@link getFocusableIn}. Yep, there is typo in the function name
+ * @returns list of focusable elements inside a given top node
+ * @see {@link getFocusableNodes} for lower level access
  */
-export declare const getFocusabledIn: (topNode: HTMLElement) => FocusableIn[];
-/**
- * return list of focusable elements inside a given top node
- */
-export declare const getFocusableIn: (topNode: HTMLElement) => FocusableIn[];
+export declare const expandFocusableNodes: (topNode: HTMLElement) => FocusableNode[];
 export {};

dist/es5/focusables.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFocusableIn = exports.getFocusabledIn = void 0;
+exports.expandFocusableNodes = void 0;
 var DOMutils_1 = require("./utils/DOMutils");
@@ -9,6 +9,6 @@ var all_affected_1 = require("./utils/all-affected");
 /**
- * return list of focusable elements inside a given top node
- * @deprecated use {@link getFocusableIn}. Yep, there is typo in the function name
+ * @returns list of focusable elements inside a given top node
+ * @see {@link getFocusableNodes} for lower level access
  */
-var getFocusabledIn = function (topNode) {
+var expandFocusableNodes = function (topNode) {
     var entries = (0, all_affected_1.getAllAffectedNodes)(topNode).filter(is_1.isNotAGuard);
@@ -37,6 +37,2 @@ var commonParent = (0, parenting_1.getTopCommonParent)(topNode, topNode, entries);
 };
-exports.getFocusabledIn = getFocusabledIn;
-/**
- * return list of focusable elements inside a given top node
- */
-exports.getFocusableIn = exports.getFocusabledIn;
+exports.expandFocusableNodes = expandFocusableNodes;

dist/es5/focusInside.d.ts

 /**
- * @returns {Boolean} true, if the current focus is inside given node or nodes
+ * @returns {Boolean} true, if the current focus is inside given node or nodes.
+ * Supports nodes hidden inside shadowDom
  */
 export declare const focusInside: (topNode: HTMLElement | HTMLElement[], activeElement?: HTMLElement | undefined) => boolean;

dist/es5/focusInside.js

@@ -13,3 +13,4 @@ "use strict";
 /**
- * @returns {Boolean} true, if the current focus is inside given node or nodes
+ * @returns {Boolean} true, if the current focus is inside given node or nodes.
+ * Supports nodes hidden inside shadowDom
  */
@@ -16,0 +17,0 @@ var focusInside = function (topNode, activeElement) {

dist/es5/focusIsHidden.d.ts

 /**
- * focus is hidden FROM the focus-lock
+ * checks if focus is hidden FROM the focus-lock
  * ie contained inside a node focus-lock shall ignore
+ *
+ * This is a utility function coupled with {@link FOCUS_ALLOW} constant
+ *
  * @returns {boolean} focus is currently is in "allow" area
  */
 export declare const focusIsHidden: (inDocument?: Document) => boolean;

dist/es5/focusIsHidden.js

@@ -9,4 +9,7 @@ "use strict";
 /**
- * focus is hidden FROM the focus-lock
+ * checks if focus is hidden FROM the focus-lock
  * ie contained inside a node focus-lock shall ignore
+ *
+ * This is a utility function coupled with {@link FOCUS_ALLOW} constant
+ *
  * @returns {boolean} focus is currently is in "allow" area
@@ -13,0 +16,0 @@ */

dist/es5/focusMerge.d.ts

 /**
- * given top node(s) and the last active element return the element to be focused next
+ * The main functionality of the focus-lock package
+ *
+ * given top node(s) and the last active element returns the element to be focused next
+ * @returns element which should be focused to move focus inside
  * @param topNode
  * @param lastNode
  */
-export declare const getFocusMerge: (topNode: Element | Element[], lastNode: Element | null) => undefined | {
+export declare const focusMerge: (topNode: Element | Element[], lastNode: Element | null) => undefined | {
     node: HTMLElement;
 };

dist/es5/focusMerge.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFocusMerge = void 0;
+exports.focusMerge = void 0;
 var solver_1 = require("./solver");
@@ -20,7 +20,10 @@ var DOMutils_1 = require("./utils/DOMutils");
 /**
- * given top node(s) and the last active element return the element to be focused next
+ * The main functionality of the focus-lock package
+ *
+ * given top node(s) and the last active element returns the element to be focused next
+ * @returns element which should be focused to move focus inside
  * @param topNode
  * @param lastNode
  */
-var getFocusMerge = function (topNode, lastNode) {
+var focusMerge = function (topNode, lastNode) {
     var activeElement = (0, getActiveElement_1.getActiveElement)((0, array_1.asArray)(topNode).length > 0 ? document : (0, array_1.getFirst)(topNode).ownerDocument);
@@ -66,2 +69,2 @@ var entries = (0, all_affected_1.getAllAffectedNodes)(topNode).filter(is_1.isNotAGuard);
 };
-exports.getFocusMerge = getFocusMerge;
+exports.focusMerge = focusMerge;

dist/es5/index.d.ts

@@ -1,12 +0,19 @@
-import * as constants from './constants';
+import * as allConstants from './constants';
 import { focusInside } from './focusInside';
 import { focusIsHidden } from './focusIsHidden';
-import { getFocusMerge as focusMerge } from './focusMerge';
-import { getFocusabledIn, getFocusableIn } from './focusables';
-import { setFocus } from './setFocus';
-import { focusNextElement, focusPrevElement } from './sibling';
-import tabHook from './tabHook';
-import { getAllAffectedNodes } from './utils/all-affected';
-import { getActiveElement } from './utils/getActiveElement';
-export { tabHook, focusInside, focusIsHidden, focusMerge, getFocusableIn, getFocusabledIn, constants, getAllAffectedNodes, focusNextElement, focusPrevElement, getActiveElement, };
-export default setFocus;
+import { focusSolver } from './focusSolver';
+import { expandFocusableNodes } from './focusables';
+import { moveFocusInside } from './moveFocusInside';
+import { focusNextElement, focusPrevElement, getRelativeFocusable } from './sibling';
+import { getFocusableNodes, getTabbableNodes } from './utils/DOMutils';
+/**
+ * magic symbols to control focus behavior from DOM
+ * see description of every particular one
+ */
+declare const constants: typeof allConstants;
+export { constants, focusInside, focusIsHidden, moveFocusInside, focusSolver, expandFocusableNodes, getFocusableNodes, getTabbableNodes, focusNextElement, focusPrevElement, getRelativeFocusable, };
+/**
+ * @deprecated - please use {@link moveFocusInside} named export
+ */
+declare const deprecated_default_moveFocusInside: typeof moveFocusInside;
+export default deprecated_default_moveFocusInside;

dist/es5/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getActiveElement = exports.focusPrevElement = exports.focusNextElement = exports.getAllAffectedNodes = exports.constants = exports.getFocusabledIn = exports.getFocusableIn = exports.focusMerge = exports.focusIsHidden = exports.focusInside = exports.tabHook = void 0;
+exports.getRelativeFocusable = exports.focusPrevElement = exports.focusNextElement = exports.getTabbableNodes = exports.getFocusableNodes = exports.expandFocusableNodes = exports.focusSolver = exports.moveFocusInside = exports.focusIsHidden = exports.focusInside = exports.constants = void 0;
 var tslib_1 = require("tslib");
-var constants = (0, tslib_1.__importStar)(require("./constants"));
-exports.constants = constants;
+var allConstants = (0, tslib_1.__importStar)(require("./constants"));
 var focusInside_1 = require("./focusInside");
@@ -11,18 +10,26 @@ Object.defineProperty(exports, "focusInside", { enumerable: true, get: function () { return focusInside_1.focusInside; } });
 Object.defineProperty(exports, "focusIsHidden", { enumerable: true, get: function () { return focusIsHidden_1.focusIsHidden; } });
-var focusMerge_1 = require("./focusMerge");
-Object.defineProperty(exports, "focusMerge", { enumerable: true, get: function () { return focusMerge_1.getFocusMerge; } });
+var focusSolver_1 = require("./focusSolver");
+Object.defineProperty(exports, "focusSolver", { enumerable: true, get: function () { return focusSolver_1.focusSolver; } });
 var focusables_1 = require("./focusables");
-Object.defineProperty(exports, "getFocusabledIn", { enumerable: true, get: function () { return focusables_1.getFocusabledIn; } });
-Object.defineProperty(exports, "getFocusableIn", { enumerable: true, get: function () { return focusables_1.getFocusableIn; } });
-var setFocus_1 = require("./setFocus");
+Object.defineProperty(exports, "expandFocusableNodes", { enumerable: true, get: function () { return focusables_1.expandFocusableNodes; } });
+var moveFocusInside_1 = require("./moveFocusInside");
+Object.defineProperty(exports, "moveFocusInside", { enumerable: true, get: function () { return moveFocusInside_1.moveFocusInside; } });
 var sibling_1 = require("./sibling");
 Object.defineProperty(exports, "focusNextElement", { enumerable: true, get: function () { return sibling_1.focusNextElement; } });
 Object.defineProperty(exports, "focusPrevElement", { enumerable: true, get: function () { return sibling_1.focusPrevElement; } });
-var tabHook_1 = (0, tslib_1.__importDefault)(require("./tabHook"));
-exports.tabHook = tabHook_1.default;
-var all_affected_1 = require("./utils/all-affected");
-Object.defineProperty(exports, "getAllAffectedNodes", { enumerable: true, get: function () { return all_affected_1.getAllAffectedNodes; } });
-var getActiveElement_1 = require("./utils/getActiveElement");
-Object.defineProperty(exports, "getActiveElement", { enumerable: true, get: function () { return getActiveElement_1.getActiveElement; } });
-exports.default = setFocus_1.setFocus;
+Object.defineProperty(exports, "getRelativeFocusable", { enumerable: true, get: function () { return sibling_1.getRelativeFocusable; } });
+var DOMutils_1 = require("./utils/DOMutils");
+Object.defineProperty(exports, "getFocusableNodes", { enumerable: true, get: function () { return DOMutils_1.getFocusableNodes; } });
+Object.defineProperty(exports, "getTabbableNodes", { enumerable: true, get: function () { return DOMutils_1.getTabbableNodes; } });
+/**
+ * magic symbols to control focus behavior from DOM
+ * see description of every particular one
+ */
+var constants = allConstants;
+exports.constants = constants;
+/**
+ * @deprecated - please use {@link moveFocusInside} named export
+ */
+var deprecated_default_moveFocusInside = moveFocusInside_1.moveFocusInside;
+exports.default = deprecated_default_moveFocusInside;
 //

dist/es5/setFocus.d.ts

@@ -6,9 +6,10 @@ export declare const focusOn: (target: Element | HTMLFrameElement | HTMLElement, focusOptions?: FocusOptions | undefined) => void;
 /**
- * Sets focus at a given node. The last focused element will help to determine which element(first or last) should be focused.
+ * Control focus at a given node.
+ * The last focused element will help to determine which element(first or last) should be focused.
+ *
+ * In principle is nothing more than a wrapper around {@link focusMerge} with autofocus
+ *
  * HTML markers (see {@link import('./constants').FOCUS_AUTO} constants) can control autofocus
- * @param topNode
- * @param lastNode
- * @param options
  */
 export declare const setFocus: (topNode: HTMLElement, lastNode: Element, options?: FocusLockFocusOptions) => void;
 export {};

dist/es5/setFocus.js

@@ -17,11 +17,12 @@ "use strict";
 /**
- * Sets focus at a given node. The last focused element will help to determine which element(first or last) should be focused.
+ * Control focus at a given node.
+ * The last focused element will help to determine which element(first or last) should be focused.
+ *
+ * In principle is nothing more than a wrapper around {@link focusMerge} with autofocus
+ *
  * HTML markers (see {@link import('./constants').FOCUS_AUTO} constants) can control autofocus
- * @param topNode
- * @param lastNode
- * @param options
  */
 var setFocus = function (topNode, lastNode, options) {
     if (options === void 0) { options = {}; }
-    var focusable = (0, focusMerge_1.getFocusMerge)(topNode, lastNode);
+    var focusable = (0, focusMerge_1.focusMerge)(topNode, lastNode);
     if (lockDisabled) {
@@ -28,0 +29,0 @@ return;

dist/es5/sibling.d.ts

@@ -0,1 +1,19 @@
+/**
+ * for a given `element` in a given `scope` returns focusable siblings
+ * @param element - base element
+ * @param scope - common parent. Can be document, but better to narrow it down for performance reasons
+ * @returns {prev,next} - references to a focusable element before and after
+ * @returns undefined - if operation is not applicable
+ */
+export declare const getRelativeFocusable: (element: Element, scope: HTMLElement | Document) => {
+    prev?: undefined;
+    next?: undefined;
+    first?: undefined;
+    last?: undefined;
+} | {
+    prev: import("./utils/tabOrder").NodeIndex;
+    next: import("./utils/tabOrder").NodeIndex;
+    first: import("./utils/tabOrder").NodeIndex;
+    last: import("./utils/tabOrder").NodeIndex;
+} | undefined;
 interface FocusNextOptions {
@@ -19,12 +37,12 @@ /**
  * focuses next element in the tab-order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export declare const focusNextElement: (baseElement: Element, options?: FocusNextOptions) => void;
+export declare const focusNextElement: (fromElement: Element, options?: FocusNextOptions) => void;
 /**
  * focuses prev element in the tab order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-export declare const focusPrevElement: (baseElement: Element, options?: FocusNextOptions) => void;
+export declare const focusPrevElement: (fromElement: Element, options?: FocusNextOptions) => void;
 export {};

dist/es5/sibling.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.focusPrevElement = exports.focusNextElement = void 0;
-var setFocus_1 = require("./setFocus");
+exports.focusPrevElement = exports.focusNextElement = exports.getRelativeFocusable = void 0;
+var commands_1 = require("./commands");
 var DOMutils_1 = require("./utils/DOMutils");
+/**
+ * for a given `element` in a given `scope` returns focusable siblings
+ * @param element - base element
+ * @param scope - common parent. Can be document, but better to narrow it down for performance reasons
+ * @returns {prev,next} - references to a focusable element before and after
+ * @returns undefined - if operation is not applicable
+ */
 var getRelativeFocusable = function (element, scope) {
@@ -16,3 +23,4 @@ if (!element || !scope || !(0, DOMutils_1.contains)(scope, element)) {
     if (current === -1) {
-        return {};
+        // an edge case, when anchor element is not found
+        return undefined;
     }
@@ -26,2 +34,3 @@ return {
 };
+exports.getRelativeFocusable = getRelativeFocusable;
 var defaultOptions = function (options) {
@@ -35,12 +44,16 @@ return Object.assign({
  * focuses next element in the tab-order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-var focusNextElement = function (baseElement, options) {
+var focusNextElement = function (fromElement, options) {
     if (options === void 0) { options = {}; }
     var _a = defaultOptions(options), scope = _a.scope, cycle = _a.cycle;
-    var _b = getRelativeFocusable(baseElement, scope), next = _b.next, first = _b.first;
+    var solution = (0, exports.getRelativeFocusable)(fromElement, scope);
+    if (!solution) {
+        return;
+    }
+    var next = solution.next, first = solution.first;
     var newTarget = next || (cycle && first);
     if (newTarget) {
-        (0, setFocus_1.focusOn)(newTarget.node, options.focusOptions);
+        (0, commands_1.focusOn)(newTarget.node, options.focusOptions);
     }
@@ -51,14 +64,18 @@ };
  * focuses prev element in the tab order
- * @param baseElement - common parent to scope active element search or tab cycle order
+ * @param fromElement - common parent to scope active element search or tab cycle order
  * @param {FocusNextOptions} [options] - focus options
  */
-var focusPrevElement = function (baseElement, options) {
+var focusPrevElement = function (fromElement, options) {
     if (options === void 0) { options = {}; }
     var _a = defaultOptions(options), scope = _a.scope, cycle = _a.cycle;
-    var _b = getRelativeFocusable(baseElement, scope), prev = _b.prev, last = _b.last;
+    var solution = (0, exports.getRelativeFocusable)(fromElement, scope);
+    if (!solution) {
+        return;
+    }
+    var prev = solution.prev, last = solution.last;
     var newTarget = prev || (cycle && last);
     if (newTarget) {
-        (0, setFocus_1.focusOn)(newTarget.node, options.focusOptions);
+        (0, commands_1.focusOn)(newTarget.node, options.focusOptions);
     }
 };
 exports.focusPrevElement = focusPrevElement;

dist/es5/utils/all-affected.d.ts

 /**
  * returns all "focus containers" inside a given node
- * @param node
- * @returns {T}
+ * @param node - node or nodes to look inside
+ * @returns Element[]
  */
 export declare const getAllAffectedNodes: (node: Element | Element[]) => Element[];

dist/es5/utils/all-affected.js

@@ -41,4 +41,4 @@ "use strict";
  * returns all "focus containers" inside a given node
- * @param node
- * @returns {T}
+ * @param node - node or nodes to look inside
+ * @returns Element[]
  */
@@ -45,0 +45,0 @@ var getAllAffectedNodes = function (node) {

dist/es5/utils/DOMutils.d.ts

@@ -11,11 +11,23 @@ import { VisibilityCache } from './is';
 /**
- * only tabbable ones
- * (but with guards which would be ignored)
+ * !__WARNING__! Low level API.
+ * @returns all tabbable nodes
+ *
+ * @see {@link getFocusableNodes} to get any focusable element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
 export declare const getTabbableNodes: (topNodes: Element[], visibilityCache: VisibilityCache, withGuards?: boolean | undefined) => NodeIndex[];
 /**
- * actually anything "focusable", not only tabbable
- * (without guards, as long as they are not expected to be focused)
+ * !__WARNING__! Low level API.
+ *
+ * @returns anything "focusable", not only tabbable. The difference is in `tabIndex=-1`
+ * (without guards, as long as they are not expected to be ever focused)
+ *
+ * @see {@link getTabbableNodes} to get only tabble nodes element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
-export declare const getAllTabbableNodes: (topNodes: Element[], visibilityCache: VisibilityCache) => NodeIndex[];
+export declare const getFocusableNodes: (topNodes: Element[], visibilityCache: VisibilityCache) => NodeIndex[];
 /**
@@ -22,0 +34,0 @@ * return list of nodes which are expected to be auto-focused

dist/es5/utils/DOMutils.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.contains = exports.parentAutofocusables = exports.getAllTabbableNodes = exports.getTabbableNodes = exports.filterAutoFocusable = exports.filterFocusable = void 0;
+exports.contains = exports.parentAutofocusables = exports.getFocusableNodes = exports.getTabbableNodes = exports.filterAutoFocusable = exports.filterFocusable = void 0;
 var array_1 = require("./array");
@@ -25,4 +25,9 @@ var is_1 = require("./is");
 /**
- * only tabbable ones
- * (but with guards which would be ignored)
+ * !__WARNING__! Low level API.
+ * @returns all tabbable nodes
+ *
+ * @see {@link getFocusableNodes} to get any focusable element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
@@ -34,9 +39,16 @@ var getTabbableNodes = function (topNodes, visibilityCache, withGuards) {
 /**
- * actually anything "focusable", not only tabbable
- * (without guards, as long as they are not expected to be focused)
+ * !__WARNING__! Low level API.
+ *
+ * @returns anything "focusable", not only tabbable. The difference is in `tabIndex=-1`
+ * (without guards, as long as they are not expected to be ever focused)
+ *
+ * @see {@link getTabbableNodes} to get only tabble nodes element
+ *
+ * @param topNodes - array of top level HTMLElements to search inside
+ * @param visibilityCache - an cache to store intermediate measurements. Expected to be a fresh `new Map` on every call
  */
-var getAllTabbableNodes = function (topNodes, visibilityCache) {
+var getFocusableNodes = function (topNodes, visibilityCache) {
     return (0, tabOrder_1.orderByTabIndex)((0, exports.filterFocusable)((0, tabUtils_1.getFocusables)(topNodes), visibilityCache), false);
 };
-exports.getAllTabbableNodes = getAllTabbableNodes;
+exports.getFocusableNodes = getFocusableNodes;
 /**
@@ -43,0 +55,0 @@ * return list of nodes which are expected to be auto-focused

dist/es5/utils/getActiveElement.d.ts

@@ -0,1 +1,5 @@
+/**
+ * returns current active element. If the active element is a "container" itself(shadowRoot or iframe) returns active element inside it
+ * @param [inDocument]
+ */
 export declare const getActiveElement: (inDocument?: Document | ShadowRoot | undefined) => HTMLElement | undefined;

dist/es5/utils/getActiveElement.js

@@ -8,2 +8,6 @@ "use strict";
 var safe_1 = require("./safe");
+/**
+ * returns current active element. If the active element is a "container" itself(shadowRoot or iframe) returns active element inside it
+ * @param [inDocument]
+ */
 var getActiveElement = function (inDocument) {
@@ -10,0 +14,0 @@ if (inDocument === void 0) { inDocument = document; }

package.json

 {
   "name": "focus-lock",
-  "version": "0.11.6",
+  "version": "1.0.0",
   "description": "DOM trap for a focus",
@@ -5,0 +5,0 @@ "main": "dist/es5/index.js",

README.md

@@ -7,4 +7,7 @@ # focus-lock
 
-# Consumers
+**Important** - this is a low level package to be used in order to create "focus lock".
+It does not provide any "lock" capabilities by itself, only helpers you can use to create one
 
+# Focus-lock implementations
+
 This is a base package for:
@@ -19,10 +22,9 @@
 
-Provides a low level API, to be used by final realization.
-Usually everything can be solved in 3 lines
+The common use case will look like final realization.
 
 ```js
-import moveFocusInside, { focusInside } from 'focus-lock';
+import { moveFocusInside, focusInside } from 'focus-lock';
 
-if (topNode && !focusInside(topNode)) {
-  moveFocusInside(topNode, lastActiveFocus);
+if (someNode && !focusInside(someNode)) {
+  moveFocusInside(someNode, lastActiveFocus /* very important to know */);
 }
@@ -33,2 +35,19 @@ ```
 
+### Get focusable nodes
+
+Returns visible and focusable nodes
+
+```ts
+import { expandFocusableNodes, getFocusableNodes, getTabbleNodes } from 'focus-lock';
+
+// returns an "extended information" but focusable nodes inside. To be used for advances cases (react-focus-lock)
+expandFocusableNodes(singleNodes);
+
+// returns all focusable nodes inside given locations
+getFocusableNodes([many, nodes])[0].node.focus();
+
+// returns all nodes reacheable in the "taborder" inside given locations
+getTabbleNodes([many, nodes])[0].node.focus();
+```
+
 ### Programmatic focus management
@@ -35,0 +54,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

157954

increased by22.97%

Number of package files

160

increased by12.68%

Lines of code

3789

increased by23.42%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

111

increased by20.65%

No dependency changes