refactor(aria/grid): support deferred focus target

Author: ok7sai

goldens/aria/grid/index.api.md

@@ -64,7 +64,7 @@ export class GridCellWidget {
     readonly deactivated: _angular_core.OutputEmitterRef<FocusEvent | KeyboardEvent | undefined>;
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly element: HTMLElement;
-    readonly focusTarget: _angular_core.InputSignal<ElementRef<any> | HTMLElement | undefined>;
+    readonly focusTarget: _angular_core.InputSignal<ElementResolver<HTMLElement>>;
     readonly id: _angular_core.InputSignal<string>;
     get isActivated(): Signal<boolean>;
     readonly _pattern: GridCellWidgetPattern;

goldens/aria/private/index.api.md

@@ -5,6 +5,7 @@
 ```ts
 
 import * as _angular_core from '@angular/core';
+import { ElementRef } from '@angular/core';
 import { OnDestroy } from '@angular/core';
 import { untracked } from '@angular/core/primitives/signals';
 
@@ -291,6 +292,9 @@ export class DeferredContentAware {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DeferredContentAware, never>;
 }
 
+// @public
+export type ElementResolver<T = HTMLElement> = ElementRef<T> | T | undefined | null | ((context: HTMLElement) => T | null | undefined);
+
 // @public
 export interface GridCellInputs extends GridCell {
     colIndex: SignalLike<number | undefined>;
@@ -334,7 +338,7 @@ export interface GridCellWidgetInputs {
     cell: SignalLike<GridCellPattern>;
     disabled: SignalLike<boolean>;
     element: SignalLike<HTMLElement>;
-    focusTarget: SignalLike<HTMLElement | undefined>;
+    focusTarget: SignalLike<ElementResolver<HTMLElement>>;
     widgetType: SignalLike<'simple' | 'complex' | 'editable'>;
 }
 
@@ -649,6 +653,9 @@ export class OptionPattern<V> {
     readonly value: SignalLike<V>;
 }
 
+// @public
+export function resolveElement<T = HTMLElement>(resolver: ElementResolver<T>, context: HTMLElement): T | undefined;
+
 // @public (undocumented)
 export function signal<T>(initialValue: T): WritableSignalLike<T>;
 

src/aria/grid/grid-cell-widget.ts

@@ -18,7 +18,7 @@ import {
   output,
   Signal,
 } from '@angular/core';
-import {GridCellWidgetPattern} from '../private';
+import {GridCellWidgetPattern, ElementResolver} from '../private';
 import {GRID_CELL} from './grid-tokens';
 
 /**
@@ -72,7 +72,7 @@ export class GridCellWidget {
   readonly disabled = input(false, {transform: booleanAttribute});
 
   /** The target that will receive focus instead of the widget. */
-  readonly focusTarget = input<ElementRef | HTMLElement | undefined>();
+  readonly focusTarget = input<ElementResolver<HTMLElement>>();
 
   /** Emits when the widget is activated. */
   readonly activated = output<KeyboardEvent | FocusEvent | undefined>();
@@ -96,10 +96,6 @@ export class GridCellWidget {
     ...this,
     element: () => this.element,
     cell: () => this._cell._pattern,
-    focusTarget: computed(() => {
-      const target = this.focusTarget();
-      return target instanceof ElementRef ? target.nativeElement : target;
-    }),
   });
 
   /** Whether the widget is activated. */
@@ -109,9 +105,10 @@ export class GridCellWidget {
 
   constructor() {
     afterRenderEffect(() => {
-      const activateEvent = this._pattern.lastActivateEvent();
-      if (activateEvent) {
+      if (this._pattern.isActivated()) {
+        const activateEvent = this._pattern.lastActivateEvent();
         this.activated.emit(activateEvent);
+        this._pattern.focus();
       }
     });
 

src/aria/grid/grid.spec.ts

@@ -972,6 +972,7 @@ describe('Grid directives', () => {
         fixture.detectChanges();
 
         expect(widgetDirective.isActivated()).toBeTrue();
+        expect(fixture.componentInstance.onActivated).toHaveBeenCalled();
       });
 
       it('should lose active state when deactivate() is called programmatically', () => {

src/aria/private/BUILD.bazel

@@ -1,14 +1,41 @@
-load("//tools:defaults.bzl", "ts_project")
+load("//tools:defaults.bzl", "ng_web_test_suite", "ts_project")
 
 package(default_visibility = ["//visibility:public"])
 
+ts_project(
+    name = "element-resolver",
+    srcs = ["element-resolver.ts"],
+    deps = [
+        "//:node_modules/@angular/core",
+    ],
+)
+
+ts_project(
+    name = "unit_test_sources",
+    testonly = True,
+    srcs = ["element-resolver.spec.ts"],
+    deps = [
+        ":element-resolver",
+        "//:node_modules/@angular/core",
+    ],
+)
+
+ng_web_test_suite(
+    name = "unit_tests",
+    deps = [":unit_test_sources"],
+)
+
 ts_project(
     name = "private",
     srcs = glob(
         ["**/*.ts"],
-        exclude = ["**/*.spec.ts"],
+        exclude = [
+            "**/*.spec.ts",
+            "element-resolver.ts",
+        ],
     ),
     deps = [
+        ":element-resolver",
         "//:node_modules/@angular/core",
         "//src/aria/private/accordion",
         "//src/aria/private/behaviors/signal-like",

src/aria/private/element-resolver.spec.ts

@@ -0,0 +1,51 @@
+import {ElementRef} from '@angular/core';
+import {resolveElement} from './element-resolver';
+
+describe('ElementResolver', () => {
+  let context: HTMLElement;
+
+  beforeEach(() => {
+    context = document.createElement('div');
+    context.id = 'context-host';
+  });
+
+  describe('resolveElement', () => {
+    it('should resolve a direct DOM element', () => {
+      const target = document.createElement('span');
+      expect(resolveElement(target, context)).toBe(target);
+    });
+
+    it('should resolve an ElementRef transparently', () => {
+      const target = document.createElement('span');
+      const elementRef = new ElementRef(target);
+      expect(resolveElement(elementRef, context)).toBe(target);
+    });
+
+    it('should resolve null as undefined', () => {
+      expect(resolveElement(null, context)).toBeUndefined();
+    });
+
+    it('should resolve undefined as undefined', () => {
+      expect(resolveElement(undefined, context)).toBeUndefined();
+    });
+
+    it('should evaluate a resolution function', () => {
+      const target = document.createElement('span');
+      const resolver = (ctx: HTMLElement) => {
+        expect(ctx).toBe(context);
+        return target;
+      };
+      expect(resolveElement(resolver, context)).toBe(target);
+    });
+
+    it('should evaluate a resolution function returning null', () => {
+      const resolver = () => null;
+      expect(resolveElement(resolver, context)).toBeUndefined();
+    });
+
+    it('should evaluate a resolution function returning undefined', () => {
+      const resolver = () => undefined;
+      expect(resolveElement(resolver, context)).toBeUndefined();
+    });
+  });
+});

src/aria/private/element-resolver.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {ElementRef} from '@angular/core';
+
+/** A type that allows lazy resolution of a DOM Element. */
+export type ElementResolver<T = HTMLElement> =
+  | ElementRef<T>
+  | T
+  | undefined
+  | null
+  | ((context: HTMLElement) => T | null | undefined);
+
+/** Evaluates an ElementResolver to return the underlying DOM element, or undefined. */
+export function resolveElement<T = HTMLElement>(
+  resolver: ElementResolver<T>,
+  context: HTMLElement,
+): T | undefined {
+  if (typeof resolver === 'function') {
+    return (resolver as Function)(context) ?? undefined;
+  }
+  return (resolver instanceof ElementRef ? resolver.nativeElement : resolver) ?? undefined;
+}

src/aria/private/grid/BUILD.bazel

@@ -12,6 +12,7 @@ ts_project(
     ],
     deps = [
         "//:node_modules/@angular/core",
+        "//src/aria/private:element-resolver",
         "//src/aria/private/behaviors/event-manager",
         "//src/aria/private/behaviors/grid",
         "//src/aria/private/behaviors/list-focus",

src/aria/private/grid/widget.ts

@@ -14,6 +14,7 @@ import {
   WritableSignalLike,
 } from '../behaviors/signal-like/signal-like';
 import type {GridCellPattern} from './cell';
+import {ElementResolver, resolveElement} from '../element-resolver';
 
 /** The inputs for the `GridCellWidgetPattern`. */
 export interface GridCellWidgetInputs {
@@ -30,7 +31,7 @@ export interface GridCellWidgetInputs {
   widgetType: SignalLike<'simple' | 'complex' | 'editable'>;
 
   /** The element that will receive focus when the widget is activated. */
-  focusTarget: SignalLike<HTMLElement | undefined>;
+  focusTarget: SignalLike<ElementResolver<HTMLElement>>;
 }
 
 /** The UI pattern for a widget inside a grid cell. */
@@ -39,9 +40,8 @@ export class GridCellWidgetPattern {
   readonly element: SignalLike<HTMLElement> = () => this.inputs.element();
 
   /** The element that should receive focus. */
-  readonly widgetHost: SignalLike<HTMLElement> = computed(
-    () => this.inputs.focusTarget() ?? this.element(),
-  );
+  readonly widgetHost: SignalLike<HTMLElement> = () =>
+    resolveElement(this.inputs.focusTarget(), this.element()) ?? this.element();
 
   /** Whether the widget is disabled. */
   readonly disabled: SignalLike<boolean> = computed(

src/aria/private/public-api.ts

@@ -25,3 +25,4 @@ export * from './grid/row';
 export * from './grid/cell';
 export * from './grid/widget';
 export * from './deferred-content';
+export * from './element-resolver';