refactor(aria/grid): support deferred focus target

Author: ok7sai

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

@@ -15,6 +15,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 extends Omit<ListNavigationItem, 'index'> {
@@ -28,7 +29,7 @@ export interface GridCellWidgetInputs extends Omit<ListNavigationItem, 'index'>
   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. */
@@ -40,9 +41,8 @@ export class GridCellWidgetPattern implements ListNavigationItem {
   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();
 
   /** The index of the widget within the cell. */
   readonly index: SignalLike<number> = 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';

src/components-examples/aria/grid/grid-table/grid-table-example.html

@@ -1,7 +1,7 @@
 <table ngGrid class="example-table">
   <thead>
     <tr ngGridRow class="example-header-row">
-      <th ngGridCell class="example-cell example-cell-checkbox">
+      <th ngGridCell role="columnheader" class="example-cell example-cell-checkbox">
         <mat-checkbox
           ngGridCellWidget
           [focusTarget]="cb._inputElement"
@@ -12,9 +12,9 @@
           #cb="matCheckbox"
         ></mat-checkbox>
       </th>
-      <th ngGridCell class="example-cell">Summary</th>
-      <th ngGridCell class="example-cell">Assignee</th>
-      <th ngGridCell class="example-cell">Tags</th>
+      <th ngGridCell role="columnheader" class="example-cell">Summary</th>
+      <th ngGridCell role="columnheader" class="example-cell">Assignee</th>
+      <th ngGridCell role="columnheader" class="example-cell">Tags</th>
     </tr>
   </thead>
   <tbody>
@@ -34,24 +34,26 @@
             role="button"
             ngGridCellWidget
             widgetType="editable"
-            (activated)="startEdit($event, task, summaryInput)"
+            [focusTarget]="findSummaryInput"
+            (activated)="startEdit($event, task)"
             (deactivated)="completeEdit($event, task)"
-            (click)="onClickEdit(widget, task, summaryInput)"
             #widget="ngGridCellWidget"
           >
-            <span [class.example-hidden]="widget.isActivated()">{{task.summary()}}</span>
-            <span
-              aria-hidden="true"
-              class="material-symbols-outlined example-edit-icon"
-              [class.example-hidden]="widget.isActivated()"
-              >edit</span
-            >
-            <mat-form-field
-              [class.example-hidden]="!widget.isActivated()"
-              subscriptSizing="dynamic"
-            >
-              <input matInput [(ngModel)]="tempInput" #summaryInput />
-            </mat-form-field>
+            @if (!widget.isActivated()) {
+              <span>{{task.summary()}}</span>
+              <span
+                aria-hidden="true"
+                class="material-symbols-outlined example-edit-icon"
+                (click)="widget.activate()"
+                >edit</span
+              >
+            } @else {
+              <mat-form-field
+                subscriptSizing="dynamic"
+              >
+                <input matInput class="summary-input" [(ngModel)]="tempInput" />
+              </mat-form-field>
+            }
           </div>
         </td>
         <td ngGridCell class="example-cell example-cell-assignee">

src/components-examples/aria/grid/grid-table/grid-table-example.ts

@@ -59,13 +59,11 @@ export class GridTableExample {
 
   readonly tasks: WritableSignal<TaskRow[]> = signal(this._createRows());
 
-  startEdit(
-    event: KeyboardEvent | FocusEvent | undefined,
-    task: TaskRow,
-    inputEl: HTMLInputElement,
-  ): void {
+  findSummaryInput = (host: HTMLElement) =>
+    host.querySelector<HTMLInputElement>('input.summary-input');
+
+  startEdit(event: KeyboardEvent | FocusEvent | undefined, task: TaskRow): void {
     this.tempInput.set(task.summary());
-    inputEl.focus();
 
     if (!(event instanceof KeyboardEvent)) return;
 
@@ -75,13 +73,6 @@ export class GridTableExample {
     }
   }
 
-  onClickEdit(widget: GridCellWidget, task: TaskRow, inputEl: HTMLInputElement) {
-    if (widget.isActivated()) return;
-
-    widget.activate();
-    setTimeout(() => this.startEdit(undefined, task, inputEl));
-  }
-
   completeEdit(event: KeyboardEvent | FocusEvent | undefined, task: TaskRow): void {
     if (!(event instanceof KeyboardEvent)) {
       return;