feat(core): elementFocus add writable focus control

Author: vs-borodin

projects/core/elements/element-focus/index.test.ts

@@ -2,71 +2,70 @@ import { Component, ElementRef, inject, signal, viewChild } from '@angular/core'
 import { TestBed } from '@angular/core/testing';
 import { elementFocus } from './index';
 
-// @TODO: add tests with focusVisible
 describe(elementFocus.name, () => {
   describe('with reactive target (signal query)', () => {
     describe('focus state tracking', () => {
       @Component({ template: '<input #input />' })
       class TestComponent {
         readonly input = viewChild<ElementRef>('input');
-        readonly isFocused = elementFocus(this.input);
+        readonly childFocused = elementFocus(this.input);
       }
 
       function createComponent() {
         const fixture = TestBed.createComponent(TestComponent);
         fixture.detectChanges();
         return {
           component: fixture.componentInstance,
-          target: fixture.nativeElement.querySelector('input'),
+          focusableChildEl: fixture.nativeElement.querySelector('input'),
         };
       }
 
       it('should be false initially', () => {
         const { component } = createComponent();
 
-        expect(component.isFocused()).toBe(false);
+        expect(component.childFocused()).toBe(false);
       });
 
       it('should handle multiple focus cycles', () => {
-        const { component, target } = createComponent();
+        const { component, focusableChildEl } = createComponent();
 
-        target.dispatchEvent(new FocusEvent('focus'));
-        expect(component.isFocused()).toBe(true);
+        focusableChildEl.dispatchEvent(new FocusEvent('focus'));
+        expect(component.childFocused()).toBe(true);
 
-        target.dispatchEvent(new FocusEvent('blur'));
-        expect(component.isFocused()).toBe(false);
+        focusableChildEl.dispatchEvent(new FocusEvent('blur'));
+        expect(component.childFocused()).toBe(false);
 
-        target.dispatchEvent(new FocusEvent('focus'));
-        expect(component.isFocused()).toBe(true);
+        focusableChildEl.dispatchEvent(new FocusEvent('focus'));
+        expect(component.childFocused()).toBe(true);
       });
     });
 
     describe('child element destroy', () => {
       it('should reset to false when element is destroyed', () => {
         @Component({
           template: `
-            @if (show()) {
+            @if (childShown()) {
             <input #input />
             }
           `,
         })
         class ConditionalComponent {
           readonly input = viewChild<ElementRef>('input');
-          readonly isFocused = elementFocus(this.input);
-          readonly show = signal(true);
+          readonly childFocused = elementFocus(this.input);
+          readonly childShown = signal(true);
         }
 
         const fixture = TestBed.createComponent(ConditionalComponent);
         fixture.detectChanges();
         const element = fixture.nativeElement.querySelector('input');
         element.dispatchEvent(new FocusEvent('focus'));
 
-        expect(fixture.componentInstance.isFocused()).toBe(true);
+        expect(fixture.componentInstance.childFocused()).toBe(true);
 
-        fixture.componentInstance.show.set(false);
+        fixture.componentInstance.childShown.set(false);
         fixture.detectChanges();
 
-        expect(fixture.componentInstance.isFocused()).toBe(false);
+        expect(fixture.componentInstance.childFocused()).toBe(false);
       });
     });
   });
@@ -84,7 +83,7 @@ describe(elementFocus.name, () => {
         fixture.detectChanges();
         return {
           component: fixture.componentInstance,
-          target: fixture.nativeElement,
+          componentHostEl: fixture.nativeElement,
         };
       }
 
@@ -95,15 +94,15 @@ describe(elementFocus.name, () => {
       });
 
       it('should handle multiple focus cycles', () => {
-        const { component, target } = createComponent();
+        const { component, componentHostEl } = createComponent();
 
-        target.dispatchEvent(new FocusEvent('focus'));
+        componentHostEl.dispatchEvent(new FocusEvent('focus'));
         expect(component.isFocused()).toBe(true);
 
-        target.dispatchEvent(new FocusEvent('blur'));
+        componentHostEl.dispatchEvent(new FocusEvent('blur'));
         expect(component.isFocused()).toBe(false);
 
-        target.dispatchEvent(new FocusEvent('focus'));
+        componentHostEl.dispatchEvent(new FocusEvent('focus'));
         expect(component.isFocused()).toBe(true);
       });
     });
@@ -131,4 +130,98 @@ describe(elementFocus.name, () => {
       });
     });
   });
+
+  describe('focus control via set()', () => {
+    @Component({ template: '<input #input />' })
+    class TestComponent {
+      readonly input = viewChild<ElementRef>('input');
+      readonly childFocused = elementFocus(this.input);
+    }
+
+    function createComponent() {
+      const fixture = TestBed.createComponent(TestComponent);
+      fixture.detectChanges();
+      return {
+        component: fixture.componentInstance,
+        focusableChildEl: fixture.nativeElement.querySelector('input') as HTMLInputElement,
+      };
+    }
+
+    it('should set focus when set(true) is called', () => {
+      const { component, focusableChildEl } = createComponent();
+
+      component.childFocused.set(true);
+
+      expect(focusableChildEl).toBe(document.activeElement);
+      expect(component.childFocused()).toBe(true);
+    });
+
+    it('should remove focus when set(false) is called', () => {
+      const { component, focusableChildEl } = createComponent();
+
+      focusableChildEl.focus();
+      expect(component.childFocused()).toBe(true);
+
+      component.childFocused.set(false);
+
+      expect(focusableChildEl).not.toBe(document.activeElement);
+      expect(component.childFocused()).toBe(false);
+    });
+
+    it('should not call focus() if already focused', () => {
+      const { component, focusableChildEl } = createComponent();
+
+      focusableChildEl.focus();
+      const spy = jest.spyOn(focusableChildEl, 'focus');
+
+      component.childFocused.set(true);
+
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it('should not call blur() if not focused', () => {
+      const { component, focusableChildEl } = createComponent();
+      const spy = jest.spyOn(focusableChildEl, 'blur');
+
+      component.childFocused.set(false);
+
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it('should support update() method', () => {
+      const { component } = createComponent();
+
+      component.childFocused.set(true);
+      expect(component.childFocused()).toBe(true);
+
+      component.childFocused.update(v => !v);
+      expect(component.childFocused()).toBe(false);
+    });
+  });
+
+  describe('preventScroll option', () => {
+    @Component({ template: '<input #input />' })
+    class TestComponent {
+      readonly input = viewChild<ElementRef>('input');
+      readonly childFocused = elementFocus(this.input, { preventScroll: true });
+    }
+
+    function createComponent() {
+      const fixture = TestBed.createComponent(TestComponent);
+      fixture.detectChanges();
+      return {
+        component: fixture.componentInstance,
+        focusableChildEl: fixture.nativeElement.querySelector('input') as HTMLInputElement,
+      };
+    }
+
+    it('should call focus with preventScroll option', () => {
+      const { component, focusableChildEl } = createComponent();
+      const spy = jest.spyOn(focusableChildEl, 'focus');
+
+      component.childFocused.set(true);
+
+      expect(spy).toHaveBeenCalledWith({ preventScroll: true });
+    });
+  });
 });

projects/core/elements/element-focus/index.ts

@@ -1,5 +1,5 @@
-import { type CreateSignalOptions, signal, type Signal } from '@angular/core';
-import { constSignal, setupContext } from '@signality/core/internal';
+import { type CreateSignalOptions, signal, type WritableSignal } from '@angular/core';
+import { proxySignal, setupContext, toElement } from '@signality/core/internal';
 import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
 import { listener } from '@signality/core/browser/listener';
 import { onDisconnect } from '@signality/core/elements/on-disconnect';
@@ -14,24 +14,29 @@ export interface ElementFocusOptions extends CreateSignalOptions<boolean>, WithI
    * @default false
    */
   readonly focusVisible?: boolean;
+
+  /**
+   * Prevent scrolling to the element when it is focused.
+   * @default false
+   */
+  readonly preventScroll?: boolean;
 }
 
 /**
  * Reactive tracking of focus state on an element.
- * Detects when an element gains or loses focus.
+ * Detects when an element gains or loses focus, and allows programmatically setting focus.
  *
  * @param target - The element to track focus state on
- * @param options - Optional configuration including focusVisible mode and injector
- * @returns A signal that is `true` when the element has focus
+ * @param options - Optional configuration including focusVisible, preventScroll and injector
+ * @returns A writable signal that is `true` when the element has focus
  *
  * @example
  * ```typescript
  * @Component({
  *   template: `
  *     <input #input [class.focused]="isFocused()" />
- *     @if (isFocused()) {
- *       <p>Input is focused</p>
- *     }
+ *     <button (click)="isFocused.set(true)">Focus Input</button>
+ *     <button (click)="isFocused.set(false)">Blur Input</button>
  *   `
  * })
  * export class FocusDemo {
@@ -43,15 +48,17 @@ export interface ElementFocusOptions extends CreateSignalOptions<boolean>, WithI
 export function elementFocus(
   target: MaybeElementSignal<HTMLElement>,
   options?: ElementFocusOptions
-): Signal<boolean> {
+): WritableSignal<boolean> {
   const { runInContext } = setupContext(options?.injector, elementFocus);
 
   return runInContext(({ isServer }) => {
     if (isServer) {
-      return constSignal(false);
+      return signal(false, options);
     }
 
     const focusVisible = options?.focusVisible ?? false;
+    const preventScroll = options?.preventScroll ?? false;
+
     const focused = signal<boolean>(false, options);
 
     listener(target, 'focus', e => {
@@ -62,8 +69,21 @@ export function elementFocus(
       focused.set(false);
     });
 
-    onDisconnect(target, () => focused.set(false));
+    onDisconnect(target, () => {
+      focused.set(false);
+    });
 
-    return focused.asReadonly();
+    return proxySignal(focused, {
+      set: (value: boolean) => {
+        const el = toElement(target);
+        const hasFocus = el?.matches(':focus') ?? false;
+
+        if (value && !hasFocus) {
+          el?.focus({ preventScroll });
+        } else if (!value && hasFocus) {
+          el?.blur();
+        }
+      },
+    });
   });
 }