refactor: Updated API documentation and naming

IgniteUI · May 20, 2024 · 945326c · 945326c
1 parent a62d550
commit 945326c
Show file tree

Hide file tree

Showing 8 changed files with 49 additions and 28 deletions.
diff --git a/src/components/button-group/toggle-button.ts b/src/components/button-group/toggle-button.ts
@@ -2,7 +2,7 @@ import { LitElement, html } from 'lit';
 import { property, query } from 'lit/decorators.js';
 
 import { themes } from '../../theming/theming-decorator.js';
-import { createFocusRing } from '../common/controllers/focus-ring.js';
+import { addKeyboardFocusRing } from '../common/controllers/focus-ring.js';
 import { registerComponent } from '../common/definitions/register.js';
 import { partNameMap } from '../common/util.js';
 import { styles } from './themes/button.base.css.js';
@@ -34,7 +34,7 @@ export default class IgcToggleButtonComponent extends LitElement {
     registerComponent(IgcToggleButtonComponent);
   }
 
-  private _focusManager = createFocusRing(this);
+  private _kbFocus = addKeyboardFocusRing(this);
 
   @query('[part="toggle"]', true)
   private _nativeButton!: HTMLButtonElement;
@@ -82,15 +82,15 @@ export default class IgcToggleButtonComponent extends LitElement {
       <button
         part=${partNameMap({
           toggle: true,
-          focused: this._focusManager.focused,
+          focused: this._kbFocus.focused,
         })}
         type="button"
         ?disabled=${this.disabled}
         .ariaLabel=${this.ariaLabel}
         aria-pressed=${this.selected}
         aria-disabled=${this.disabled}
-        @click=${this._focusManager.reset}
-        @blur=${this._focusManager.reset}
+        @click=${this._kbFocus.reset}
+        @blur=${this._kbFocus.reset}
       >
         <slot></slot>
       </button>

diff --git a/src/components/button/button-base.ts b/src/components/button/button-base.ts
@@ -3,7 +3,7 @@ import { property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 
 import { EventEmitterMixin } from '../common//mixins/event-emitter.js';
-import { createFocusRing } from '../common/controllers/focus-ring.js';
+import { addKeyboardFocusRing } from '../common/controllers/focus-ring.js';
 import { blazorDeepImport } from '../common/decorators/blazorDeepImport.js';
 import type { Constructor } from '../common/mixins/constructor.js';
 import { SizableMixin } from '../common/mixins/sizable.js';
@@ -25,7 +25,7 @@ export abstract class IgcButtonBaseComponent extends SizableMixin(
     delegatesFocus: true,
   };
 
-  private _focusManager = createFocusRing(this);
+  private _kbFocus = addKeyboardFocusRing(this);
 
   protected __internals: ElementInternals;
   protected _disabled = false;
@@ -119,11 +119,11 @@ export abstract class IgcButtonBaseComponent extends SizableMixin(
 
   protected handleBlur() {
     this.emitEvent('igcBlur');
-    this._focusManager.reset();
+    this._kbFocus.reset();
   }
 
   protected handleClick() {
-    this._focusManager.reset();
+    this._kbFocus.reset();
     switch (this.type) {
       case 'submit':
         return this.form?.requestSubmit();
@@ -144,7 +144,7 @@ export abstract class IgcButtonBaseComponent extends SizableMixin(
       <button
         part=${partNameMap({
           base: true,
-          focused: this._focusManager.focused,
+          focused: this._kbFocus.focused,
         })}
         aria-label=${ifDefined(this.ariaLabel ?? nothing)}
         ?disabled=${this.disabled}
@@ -163,7 +163,7 @@ export abstract class IgcButtonBaseComponent extends SizableMixin(
       <a
         part=${partNameMap({
           base: true,
-          focused: this._focusManager.focused,
+          focused: this._kbFocus.focused,
         })}
         role="button"
         aria-label=${ifDefined(this.ariaLabel ?? nothing)}

diff --git a/src/components/checkbox/checkbox-base.ts b/src/components/checkbox/checkbox-base.ts
@@ -1,7 +1,7 @@
 import { LitElement } from 'lit';
 import { property, query, queryAssignedNodes, state } from 'lit/decorators.js';
 
-import { createFocusRing } from '../common/controllers/focus-ring.js';
+import { addKeyboardFocusRing } from '../common/controllers/focus-ring.js';
 import { alternateName } from '../common/decorators/alternateName.js';
 import { blazorDeepImport } from '../common/decorators/blazorDeepImport.js';
 import { blazorTwoWayBind } from '../common/decorators/blazorTwoWayBind.js';
@@ -26,7 +26,7 @@ export class IgcCheckboxBaseComponent extends FormAssociatedRequiredMixin(
 ) {
   protected override validators: Validator<this>[] = [requiredBooleanValidator];
 
-  protected _focusManager = createFocusRing(this);
+  protected _kbFocus = addKeyboardFocusRing(this);
   protected _value!: string;
   protected _checked = false;
 
@@ -117,7 +117,7 @@ export class IgcCheckboxBaseComponent extends FormAssociatedRequiredMixin(
 
   protected handleBlur() {
     this.emitEvent('igcBlur');
-    this._focusManager.reset();
+    this._kbFocus.reset();
   }
 
   protected handleFocus() {

diff --git a/src/components/checkbox/checkbox.ts b/src/components/checkbox/checkbox.ts
@@ -61,10 +61,10 @@ export default class IgcCheckboxComponent extends IgcCheckboxBaseComponent {
         part=${partNameMap({
           base: true,
           checked: this.checked,
-          focused: this._focusManager.focused,
+          focused: this._kbFocus.focused,
         })}
         for=${this.inputId}
-        @pointerdown=${this._focusManager.reset}
+        @pointerdown=${this._kbFocus.reset}
       >
         <input
           id=${this.inputId}

diff --git a/src/components/checkbox/switch.ts b/src/components/checkbox/switch.ts
@@ -48,7 +48,7 @@ export default class IgcSwitchComponent extends IgcCheckboxBaseComponent {
       <label
         part=${partNameMap({ base: true, checked: this.checked })}
         for=${this.inputId}
-        @pointerdown=${this._focusManager.reset}
+        @pointerdown=${this._kbFocus.reset}
       >
         <input
           id=${this.inputId}
@@ -69,7 +69,7 @@ export default class IgcSwitchComponent extends IgcCheckboxBaseComponent {
           part=${partNameMap({
             control: true,
             checked: this.checked,
-            focused: this._focusManager.focused,
+            focused: this._kbFocus.focused,
           })}
         >
           <span

diff --git a/src/components/common/controllers/focus-ring.spec.ts b/src/components/common/controllers/focus-ring.spec.ts
@@ -13,7 +13,7 @@ import {
   simulateKeyboard,
   simulatePointerDown,
 } from '../utils.spec.js';
-import { createFocusRing } from './focus-ring.js';
+import { addKeyboardFocusRing } from './focus-ring.js';
 import { tabKey } from './key-bindings.js';
 
 describe('Focus ring controller', () => {
@@ -29,7 +29,7 @@ describe('Focus ring controller', () => {
           }
         `;
 
-        public manager = createFocusRing(this);
+        public manager = addKeyboardFocusRing(this);
 
         public get button() {
           return this.renderRoot.querySelector('button')!;

diff --git a/src/components/common/controllers/focus-ring.ts b/src/components/common/controllers/focus-ring.ts
@@ -1,10 +1,20 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
 
 /* blazorSuppress */
-export class FocusRingController implements ReactiveController {
+/**
+ * A controller class which determines whether a focus ring should be shown to indicate keyboard focus.
+ * Focus rings are visible only when the user is interacting with a keyboard, not with a mouse, touch, or other input methods.
+ *
+ * By default the class attaches a keyup event handler on the component host and will update its keyboard focus
+ * state based on it.
+ */
+export class KeyboardFocusRingController implements ReactiveController {
   private readonly _host: ReactiveControllerHost & HTMLElement;
   private _focused = false;
 
+  /**
+   * Gets whether the current focus state is activated through a keyboard interaction.
+   */
   public get focused() {
     return this._focused;
   }
@@ -29,12 +39,23 @@ export class FocusRingController implements ReactiveController {
     this._host.requestUpdate();
   }
 
+  /**
+   * Resets the keyboard focus state.
+   *
+   * Usually called on blur of the component or when a pointer based interaction
+   * is executed.
+   */
   public reset = () => {
     this._focused = false;
     this._host.requestUpdate();
   };
 }
 
-export function createFocusRing(host: ReactiveControllerHost & HTMLElement) {
-  return new FocusRingController(host);
+/**
+ * Adds a {@link KeyboardFocusRingController} responsible for managing keyboard focus state.
+ */
+export function addKeyboardFocusRing(
+  host: ReactiveControllerHost & HTMLElement
+) {
+  return new KeyboardFocusRingController(host);
 }
diff --git a/src/components/radio/radio.ts b/src/components/radio/radio.ts
@@ -4,7 +4,7 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import { live } from 'lit/directives/live.js';
 
 import { themes } from '../../theming/theming-decorator.js';
-import { createFocusRing } from '../common/controllers/focus-ring.js';
+import { addKeyboardFocusRing } from '../common/controllers/focus-ring.js';
 import {
   addKeybindings,
   arrowDown,
@@ -75,7 +75,7 @@ export default class IgcRadioComponent extends FormAssociatedRequiredMixin(
 
   private inputId = `radio-${IgcRadioComponent.increment()}`;
   private labelId = `radio-label-${this.inputId}`;
-  private _focusManager = createFocusRing(this);
+  private _kbFocus = addKeyboardFocusRing(this);
 
   protected _checked = false;
   protected _value!: string;
@@ -242,7 +242,7 @@ export default class IgcRadioComponent extends FormAssociatedRequiredMixin(
 
   protected handleBlur() {
     this.emitEvent('igcBlur');
-    this._focusManager.reset();
+    this._kbFocus.reset();
   }
 
   protected handleFocus() {
@@ -271,10 +271,10 @@ export default class IgcRadioComponent extends FormAssociatedRequiredMixin(
         part=${partNameMap({
           base: true,
           checked: this.checked,
-          focused: this._focusManager.focused,
+          focused: this._kbFocus.focused,
         })}
         for=${this.inputId}
-        @pointerdown=${this._focusManager.reset}
+        @pointerdown=${this._kbFocus.reset}
       >
         <input
           id=${this.inputId}