Focus Disabled

The LmnFocusDisabledDirective is an Angular attribute directive designed to programmatically prevent an HTML element and, by default, all its focusable descendant elements from receiving focus. It achieves this by setting their tabindex to -1 and restores their original tabindex values when the directive's condition for disabling focus is no longer met.

Technical Overview

The lmnFocusDisabled directive monitors an input property (lmnFocusDisabled or unfocusable). When this input is true, the directive modifies the tabindex of the host element (unless excluded) and all its focusable children to -1, effectively removing them from the keyboard navigation flow and preventing them from being focused.

To ensure that original tabindex values are not lost, the directive stores the element's tabindex (or 'none' if no tabindex was present) in a data-tabindex-backup attribute before setting tabindex="-1". When the directive's unfocusable input becomes false, it uses this backup attribute to restore the original tabindex values, then removes the backup attribute.

The directive react to changes in its input properties (unfocusable and excludeHost) and apply or revert the focus disabling logic accordingly. It utilizes a helper function, getFocusableElements (presumably to identify elements that can naturally receive focus or have a tabindex >= 0), to find descendant elements to act upon.

Key Features

• Focus Disabling: Programmatically makes the host element and/or its focusable descendants non-focusable.
• Tabindex Management: Sets tabindex="-1" on targeted elements to disable focus.
• Original Tabindex Preservation: Saves the original tabindex of elements in a data-tabindex-backup attribute before modification.
• Tabindex Restoration: Restores the original tabindex values when focus disabling is turned off.
• Host Element Exclusion: An input (lmnFocusDisabledExcludeHost) allows the host element itself to remain focusable while its descendants are made unfocusable.

When to Use

Use the LmnFocusDisabledDirective when:

• You need to temporarily make a section of the UI non-interactive via keyboard, for example, when a modal dialog is open and the background content should not be focusable.
• You have complex components where certain child elements should be conditionally removed from the focus order based on the component's state.
• You want to manage the focusability of a group of elements without manually iterating and changing their tabindex attributes in component logic.
• To improve accessibility by guiding focus appropriately in dynamic UIs.

Implementation

Apply the [lmnFocusDisabled] directive to the HTML element whose focusability (and that of its children) you want to control.

Selector: [lmnFocusDisabled]

Inputs:

• lmnFocusDisabled (alias unfocusable): boolean (default: false).
  • When true, the directive disables focus on the host element (unless lmnFocusDisabledExcludeHost is true) and all its focusable descendant elements.
  • When false, it restores the original focusability of these elements.
• lmnFocusDisabledExcludeHost (alias excludeHost): boolean (default: false).
  • If true, the host element itself will not have its focus disabled by this directive, even if lmnFocusDisabled is true. Focus disabling will only apply to its focusable descendants.