refactor(aria/toolbar): large rework of toolbar internals (#32236)

* refactor(multiple): make ListItem.element() optional

* refactor(aria/toolbar): large rework of toolbar internals

* refactor(aria/toolbar): dev-app demo changes

Author: wagnermaciel

src/aria/listbox/listbox.ts

@@ -185,7 +185,7 @@ export class Listbox<V> {
   }
 
   scrollActiveItemIntoView(options: ScrollIntoViewOptions = {block: 'nearest'}) {
-    this._pattern.inputs.activeItem()?.element().scrollIntoView(options);
+    this._pattern.inputs.activeItem()?.element()?.scrollIntoView(options);
   }
 }
 

src/aria/private/behaviors/list-focus/list-focus.ts

@@ -15,7 +15,7 @@ export interface ListFocusItem {
   id: SignalLike<string>;
 
   /** The html element that should receive focus. */
-  element: SignalLike<HTMLElement>;
+  element: SignalLike<HTMLElement | undefined>;
 
   /** Whether an item is disabled. */
   disabled: SignalLike<boolean>;
@@ -112,7 +112,7 @@ export class ListFocus<T extends ListFocusItem> {
 
     if (opts?.focusElement || opts?.focusElement === undefined) {
       this.inputs.focusMode() === 'roving'
-        ? item.element().focus()
+        ? item.element()?.focus()
         : this.inputs.element()?.focus();
     }
 

src/aria/private/behaviors/list-navigation/list-navigation.ts

@@ -55,19 +55,29 @@ export class ListNavigation<T extends ListNavigationItem> {
 
   /** Navigates to the first item in the list. */
   first(opts?: {focusElement?: boolean}): boolean {
-    const item = this.inputs.items().find(i => this.inputs.focusManager.isFocusable(i));
+    const item = this.peekFirst();
     return item ? this.goto(item, opts) : false;
   }
 
   /** Navigates to the last item in the list. */
   last(opts?: {focusElement?: boolean}): boolean {
-    const items = this.inputs.items();
+    const item = this.peekLast();
+    return item ? this.goto(item, opts) : false;
+  }
+
+  /** Gets the first focusable item from the given list of items. */
+  peekFirst(items: T[] = this.inputs.items()): T | undefined {
+    return items.find(i => this.inputs.focusManager.isFocusable(i));
+  }
+
+  /** Gets the last focusable item from the given list of items. */
+  peekLast(items: T[] = this.inputs.items()): T | undefined {
     for (let i = items.length - 1; i >= 0; i--) {
       if (this.inputs.focusManager.isFocusable(items[i])) {
-        return this.goto(items[i], opts);
+        return items[i];
       }
     }
-    return false;
+    return;
   }
 
   /** Advances to the next or previous focusable item in the list based on the given delta. */

src/aria/private/behaviors/list/list.ts

@@ -161,8 +161,8 @@ export class List<T extends ListItem<V>, V> {
   }
 
   /** Deselects the currently active item in the list. */
-  deselect() {
-    this.selectionBehavior.deselect();
+  deselect(item?: T) {
+    this.selectionBehavior.deselect(item);
   }
 
   /** Deselects all items in the list. */

src/aria/private/listbox/option.ts

@@ -57,7 +57,7 @@ export class OptionPattern<V> {
   tabIndex = computed(() => this.listbox()?.listBehavior.getItemTabindex(this));
 
   /** The html element that should receive focus. */
-  element: SignalLike<HTMLElement>;
+  element: SignalLike<HTMLElement | undefined>;
 
   constructor(args: OptionInputs<V>) {
     this.id = args.id;

src/aria/private/menu/menu.ts

@@ -248,7 +248,7 @@ export class MenuPattern<V> {
     if (parent instanceof MenuItemPattern) {
       const grandparent = parent.inputs.parent();
       const siblings = grandparent?.inputs.items().filter(i => i !== parent);
-      const item = siblings?.find(i => i.element().contains(relatedTarget));
+      const item = siblings?.find(i => i.element()?.contains(relatedTarget));
 
       if (item) {
         return;
@@ -602,7 +602,7 @@ export class MenuItemPattern<V> implements ListItem<V> {
   searchTerm: SignalLike<string>;
 
   /** The element of the menu item. */
-  element: SignalLike<HTMLElement>;
+  element: SignalLike<HTMLElement | undefined>;
 
   /** Whether the menu item is active. */
   isActive = computed(() => this.inputs.parent()?.inputs.activeItem() === this);

src/aria/private/tabs/tabs.ts

@@ -47,7 +47,7 @@ export class TabPattern {
   readonly disabled: SignalLike<boolean>;
 
   /** The html element that should receive focus. */
-  readonly element: SignalLike<HTMLElement>;
+  readonly element: SignalLike<HTMLElement | undefined>;
 
   /** Whether the tab is selectable. */
   readonly selectable = () => true;

src/aria/private/toolbar/toolbar-widget-group.ts

@@ -6,103 +6,40 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {computed} from '@angular/core';
-import {SignalLike} from '../behaviors/signal-like/signal-like';
 import {ListItem} from '../behaviors/list/list';
+import {SignalLike} from '../behaviors/signal-like/signal-like';
 import type {ToolbarPattern} from './toolbar';
 
-/** An interface that allows sub patterns to expose the necessary controls for the toolbar. */
-export interface ToolbarWidgetGroupControls {
-  /** Whether the widget group is currently on the first item. */
-  isOnFirstItem(): boolean;
-
-  /** Whether the widget group is currently on the last item. */
-  isOnLastItem(): boolean;
-
-  /** Navigates to the next widget in the group. */
-  next(wrap: boolean): void;
-
-  /** Navigates to the previous widget in the group. */
-  prev(wrap: boolean): void;
-
-  /** Navigates to the first widget in the group. */
-  first(): void;
-
-  /** Navigates to the last widget in the group. */
-  last(): void;
-
-  /** Removes focus from the widget group. */
-  unfocus(): void;
-
-  /** Triggers the action of the currently active widget in the group. */
-  trigger(): void;
-
-  /** Navigates to the widget targeted by a pointer event. */
-  goto(event: PointerEvent): void;
-
-  /** Sets the widget group to its default initial state. */
-  setDefaultState(): void;
-}
-
 /** Represents the required inputs for a toolbar widget group. */
-export interface ToolbarWidgetGroupInputs<V>
-  extends Omit<ListItem<V>, 'searchTerm' | 'value' | 'index' | 'selectable'> {
+export interface ToolbarWidgetGroupInputs<T extends ListItem<V>, V> {
   /** A reference to the parent toolbar. */
   toolbar: SignalLike<ToolbarPattern<V> | undefined>;
 
-  /** The controls for the sub patterns associated with the toolbar. */
-  controls: SignalLike<ToolbarWidgetGroupControls | undefined>;
-}
+  /** Whether the widget group is disabled. */
+  disabled: SignalLike<boolean>;
 
-/** A group of widgets within a toolbar that provides nested navigation. */
-export class ToolbarWidgetGroupPattern<V> implements ListItem<V> {
-  /** A unique identifier for the widget. */
-  readonly id: SignalLike<string>;
+  /** The list of items within the widget group. */
+  items: SignalLike<T[]>;
 
-  /** The html element that should receive focus. */
-  readonly element: SignalLike<HTMLElement>;
+  /** Whether the group allows multiple widgets to be selected. */
+  multi: SignalLike<boolean>;
+}
 
+/** A group of widgets within a toolbar that provides nested navigation. */
+export class ToolbarWidgetGroupPattern<T extends ListItem<V>, V> {
   /** Whether the widget is disabled. */
-  readonly disabled: SignalLike<boolean>;
+  readonly disabled = () => this.inputs.disabled();
 
   /** A reference to the parent toolbar. */
-  readonly toolbar: SignalLike<ToolbarPattern<V> | undefined>;
+  readonly toolbar = () => this.inputs.toolbar();
 
-  /** The text used by the typeahead search. */
-  readonly searchTerm = () => ''; // Unused because toolbar does not support typeahead.
+  /** Whether the group allows multiple widgets to be selected. */
+  readonly multi = () => this.inputs.multi();
 
-  /** The value associated with the widget. */
+  readonly searchTerm = () => ''; // Unused because toolbar does not support typeahead.
   readonly value = () => '' as V; // Unused because toolbar does not support selection.
-
-  /** Whether the widget is selectable. */
   readonly selectable = () => true; // Unused because toolbar does not support selection.
+  readonly element = () => undefined; // Unused because toolbar does not focus the group element.
 
-  /** The position of the widget within the toolbar. */
-  readonly index = computed(() => this.toolbar()?.inputs.items().indexOf(this) ?? -1);
-
-  /** The actions that can be performed on the widget group. */
-  readonly controls: SignalLike<ToolbarWidgetGroupControls> = computed(
-    () => this.inputs.controls() ?? this._defaultControls,
-  );
-
-  /** Default toolbar widget group controls when no controls provided. */
-  private readonly _defaultControls: ToolbarWidgetGroupControls = {
-    isOnFirstItem: () => true,
-    isOnLastItem: () => true,
-    next: () => {},
-    prev: () => {},
-    first: () => {},
-    last: () => {},
-    unfocus: () => {},
-    trigger: () => {},
-    goto: () => {},
-    setDefaultState: () => {},
-  };
-
-  constructor(readonly inputs: ToolbarWidgetGroupInputs<V>) {
-    this.id = inputs.id;
-    this.element = inputs.element;
-    this.disabled = inputs.disabled;
-    this.toolbar = inputs.toolbar;
-  }
+  constructor(readonly inputs: ToolbarWidgetGroupInputs<T, V>) {}
 }

src/aria/private/toolbar/toolbar-widget.ts

@@ -10,49 +10,56 @@ import {computed} from '@angular/core';
 import {SignalLike} from '../behaviors/signal-like/signal-like';
 import {ListItem} from '../behaviors/list/list';
 import type {ToolbarPattern} from './toolbar';
+import {ToolbarWidgetGroupPattern} from './toolbar-widget-group';
 
 /** Represents the required inputs for a toolbar widget in a toolbar. */
 export interface ToolbarWidgetInputs<V>
-  extends Omit<ListItem<V>, 'searchTerm' | 'value' | 'index' | 'selectable'> {
+  extends Omit<ListItem<V>, 'searchTerm' | 'index' | 'selectable'> {
   /** A reference to the parent toolbar. */
   toolbar: SignalLike<ToolbarPattern<V>>;
+
+  /** A reference to the parent widget group. */
+  group: SignalLike<ToolbarWidgetGroupPattern<ToolbarWidgetPattern<V>, V> | undefined>;
 }
 
 export class ToolbarWidgetPattern<V> implements ListItem<V> {
   /** A unique identifier for the widget. */
-  readonly id: SignalLike<string>;
+  readonly id = () => this.inputs.id();
 
   /** The html element that should receive focus. */
-  readonly element: SignalLike<HTMLElement>;
+  readonly element = () => this.inputs.element();
 
   /** Whether the widget is disabled. */
-  readonly disabled: SignalLike<boolean>;
+  readonly disabled = () => this.inputs.disabled() || this.group()?.disabled() || false;
 
   /** A reference to the parent toolbar. */
-  readonly toolbar: SignalLike<ToolbarPattern<V>>;
+  readonly group = () => this.inputs.group();
+
+  /** A reference to the toolbar containing the widget. */
+  readonly toolbar = () => this.inputs.toolbar();
 
-  /** The tab index of the widgdet. */
+  /** The tabindex of the widget. */
   readonly tabIndex = computed(() => this.toolbar().listBehavior.getItemTabindex(this));
 
   /** The text used by the typeahead search. */
   readonly searchTerm = () => ''; // Unused because toolbar does not support typeahead.
 
   /** The value associated with the widget. */
-  readonly value = () => '' as V; // Unused because toolbar does not support selection.
+  readonly value = () => this.inputs.value();
 
   /** Whether the widget is selectable. */
   readonly selectable = () => true; // Unused because toolbar does not support selection.
 
   /** The position of the widget within the toolbar. */
   readonly index = computed(() => this.toolbar().inputs.items().indexOf(this) ?? -1);
 
+  /** Whether the widget is selected (only relevant in a selection group). */
+  readonly selected = computed(() =>
+    this.toolbar().listBehavior.inputs.value().includes(this.value()),
+  );
+
   /** Whether the widget is currently the active one (focused). */
-  readonly active = computed(() => this.toolbar().inputs.activeItem() === this);
-
-  constructor(readonly inputs: ToolbarWidgetInputs<V>) {
-    this.id = inputs.id;
-    this.element = inputs.element;
-    this.disabled = inputs.disabled;
-    this.toolbar = inputs.toolbar;
-  }
+  readonly active: SignalLike<boolean> = computed(() => this.toolbar().activeItem() === this);
+
+  constructor(readonly inputs: ToolbarWidgetInputs<V>) {}
 }