Logo for jsDocs.io

focus-lock

  • Version 1.3.6
  • Published
  • 188 kB
  • 1 dependency
  • MIT license

Install

npm i focus-lock
yarn add focus-lock
pnpm add focus-lock

Overview

DOM trap for a focus

Index

Variables

Functions

Variables

variable constants

const constants: typeof allConstants;

  • magic symbols to control focus behavior from DOM see description of every particular one

variable deprecated_default_moveFocusInside

const deprecated_default_moveFocusInside: (
    topNode: HTMLElement,
    lastNode: Element,
    options?: FocusLockFocusOptions
) => void;

Functions

function captureFocusRestore

captureFocusRestore: (
    targetElement: Element | null
) => () => Element | undefined;

  • Captures the current focused element to restore focus as close as possible in the future Handles situations where the focused element is removed from the DOM or no longer focusable moving focus to the closest focusable element

    Parameter targetElement

    element where focus should be restored

    Returns

    a function returning a new element to focus

function expandFocusableNodes

expandFocusableNodes: (topNode: HTMLElement | HTMLElement[]) => FocusableNode[];

  • traverses all related nodes (including groups) returning a list of all nodes(outer and internal) with meta information This is low-level API!

    Returns

    list of focusable elements inside a given top(!) node.

    See Also

function focusFirstElement

focusFirstElement: (scope: ScopeRef, options?: FocusBoundaryOptions) => void;

  • focuses first element in the tab-order

    Parameter options

    focus options

function focusInside

focusInside: (
    topNode: HTMLElement | HTMLElement[],
    activeElement?: HTMLElement | undefined
) => boolean;

  • Returns

    {Boolean} true, if the current focus is inside given node or nodes. Supports nodes hidden inside shadowDom

function focusIsHidden

focusIsHidden: (inDocument?: Document) => boolean;

  • 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 FOCUS_ALLOW constant

    Returns

    {boolean} focus is currently is in "allow" area

function focusLastElement

focusLastElement: (scope: ScopeRef, options?: FocusBoundaryOptions) => void;

  • focuses last element in the tab order

    Parameter options

    focus options

function focusNextElement

focusNextElement: (fromElement: Element, options?: FocusNextOptions) => void;

  • focuses next element in the tab-order

    Parameter fromElement

    common parent to scope active element search or tab cycle order

    Parameter options

    focus options

function focusPrevElement

focusPrevElement: (fromElement: Element, options?: FocusNextOptions) => void;

  • focuses prev element in the tab order

    Parameter fromElement

    common parent to scope active element search or tab cycle order

    Parameter options

    focus options

function focusSolver

focusSolver: (
    topNode: Element | Element[],
    lastNode: Element | null
) => undefined | { node: HTMLElement };

  • contains the main logic of the focus-lock package.

    ! you probably dont need this function !

    given top node(s) and the last active element returns the element to be focused next

    Parameter topNode

    Parameter lastNode

    Returns

    element which should be focused to move focus inside

function getFocusableNodes

getFocusableNodes: (
    topNodes: Element[],
    visibilityCache: VisibilityCache
) => NodeIndex[];

  • !__WARNING__! Low level API.

    Parameter topNodes

    array of top level HTMLElements to search inside

    Parameter visibilityCache

    an cache to store intermediate measurements. Expected to be a fresh new Map on every call

    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 Also

function getRelativeFocusable

getRelativeFocusable: (
    element: Element,
    scope: HTMLElement | HTMLElement[],
    useTabbables: boolean
) => UnresolvedSolution | ResolvedSolution | undefined;

  • for a given element in a given scope returns focusable siblings

    Parameter element

    base element

    Parameter scope

    common parent. Can be document, but better to narrow it down for performance reasons

    Returns

    undefined - if operation is not applicable

function getTabbableNodes

getTabbableNodes: (
    topNodes: Element[],
    visibilityCache: VisibilityCache,
    withGuards?: boolean | undefined
) => NodeIndex[];

  • !__WARNING__! Low level API.

    Parameter topNodes

    array of top level HTMLElements to search inside

    Parameter visibilityCache

    an cache to store intermediate measurements. Expected to be a fresh new Map on every call

    Returns

    all tabbable nodes

    See Also

function moveFocusInside

moveFocusInside: (
    topNode: HTMLElement,
    lastNode: Element,
    options?: FocusLockFocusOptions
) => void;

  • The main functionality of the focus-lock package

    Contains focus at a given node. The last focused element will help to determine which element(first or last) should be focused. The found element will be focused.

    This is one time action (move), not a persistent focus-lock

    HTML markers (see constants) can control autofocus

    See Also

    • focusSolver for the same functionality without autofocus

Package Files (9)

Dependencies (1)

Dev Dependencies (3)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/focus-lock.

  • Markdown
    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/focus-lock)
  • HTML
    <a href="https://www.jsdocs.io/package/focus-lock"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>