refactor(aria/tabs): Use template reference to link tabs and panels together

Author: adolgachev

goldens/aria/private/index.api.md

@@ -682,14 +682,14 @@ export function signal<T>(initialValue: T): WritableSignalLike<T>;
 export type SignalLike<T> = () => T;
 
 // @public
-export interface TabInputs extends Omit<ListNavigationItem, 'index'>, Omit<ExpansionItem, 'expandable'> {
+export interface TabInputs extends Omit<ListNavigationItem, 'index'>, Omit<ExpansionItem, 'expandable' | 'expanded'> {
     tablist: SignalLike<TabListPattern>;
     tabpanel: SignalLike<TabPanelPattern | undefined>;
-    value: SignalLike<string>;
 }
 
 // @public
 export interface TabListInputs extends Omit<ListNavigationInputs<TabPattern>, 'multi'>, Omit<ListExpansionInputs, 'multiExpandable' | 'items'> {
+    selectedTab: WritableSignalLike<TabPattern | undefined>;
     selectionMode: SignalLike<'follow' | 'explicit'>;
 }
 
@@ -709,7 +709,6 @@ export class TabListPattern {
     readonly nextKey: SignalLike<"ArrowRight" | "ArrowLeft" | "ArrowDown">;
     onKeydown(event: KeyboardEvent): void;
     onPointerdown(event: PointerEvent): void;
-    open(value: string): boolean;
     open(tab?: TabPattern): boolean;
     readonly orientation: SignalLike<'vertical' | 'horizontal'>;
     readonly pointerdown: SignalLike<PointerEventManager<PointerEvent>>;
@@ -723,7 +722,6 @@ export class TabListPattern {
 export interface TabPanelInputs extends LabelControlOptionalInputs {
     id: SignalLike<string>;
     tab: SignalLike<TabPattern | undefined>;
-    value: SignalLike<string>;
 }
 
 // @public
@@ -736,7 +734,6 @@ export class TabPanelPattern {
     readonly labelledBy: SignalLike<string | undefined>;
     readonly labelManager: LabelControl;
     readonly tabIndex: SignalLike<-1 | 0>;
-    readonly value: SignalLike<string>;
 }
 
 // @public
@@ -747,6 +744,7 @@ export class TabPattern {
     readonly disabled: SignalLike<boolean>;
     readonly element: SignalLike<HTMLElement>;
     readonly expandable: SignalLike<boolean>;
+    // (undocumented)
     readonly expanded: WritableSignalLike<boolean>;
     readonly id: SignalLike<string>;
     readonly index: SignalLike<number>;
@@ -755,7 +753,6 @@ export class TabPattern {
     open(): boolean;
     readonly selected: SignalLike<boolean>;
     readonly tabIndex: SignalLike<0 | -1>;
-    readonly value: SignalLike<string>;
 }
 
 // @public

goldens/aria/tabs/index.api.md

@@ -10,21 +10,19 @@ import { OnDestroy } from '@angular/core';
 import { OnInit } from '@angular/core';
 
 // @public
-export class Tab implements HasElement, OnInit, OnDestroy {
+export class Tab implements OnInit {
     readonly active: _angular_core.Signal<boolean>;
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly element: HTMLElement;
     readonly id: _angular_core.InputSignal<string>;
     // (undocumented)
-    ngOnDestroy(): void;
-    // (undocumented)
     ngOnInit(): void;
     open(): void;
+    readonly panel: _angular_core.InputSignal<TabPanel>;
     readonly _pattern: TabPattern;
     readonly selected: _angular_core.Signal<boolean>;
-    readonly value: _angular_core.InputSignal<string>;
     // (undocumented)
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Tab, "[ngTab]", ["ngTab"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Tab, "[ngTab]", ["ngTab"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "panel": { "alias": "panel"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
     // (undocumented)
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Tab, never>;
 }
@@ -38,69 +36,42 @@ export class TabContent {
 }
 
 // @public
-export class TabList implements OnInit, OnDestroy {
+export class TabList {
     constructor();
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly element: HTMLElement;
     readonly focusMode: _angular_core.InputSignal<"roving" | "activedescendant">;
     // (undocumented)
-    ngOnDestroy(): void;
-    // (undocumented)
-    ngOnInit(): void;
-    // (undocumented)
     _onFocus(): void;
-    open(value: string): boolean;
     readonly orientation: _angular_core.InputSignal<"vertical" | "horizontal">;
     readonly _pattern: TabListPattern;
-    // (undocumented)
-    _register(child: Tab): void;
-    readonly selectedTab: _angular_core.ModelSignal<string | undefined>;
+    readonly selectedTab: _angular_core.WritableSignal<TabPattern | undefined>;
+    readonly selectedTabIndex: _angular_core.ModelSignal<number>;
     readonly selectionMode: _angular_core.InputSignal<"follow" | "explicit">;
     readonly softDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly _tabPatterns: _angular_core.Signal<TabPattern[]>;
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
-    // (undocumented)
-    _unregister(child: Tab): void;
     readonly wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
     // (undocumented)
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TabList, "[ngTabList]", ["ngTabList"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "focusMode": { "alias": "focusMode"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "selectedTab": { "alias": "selectedTab"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "selectedTab": "selectedTabChange"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TabList, "[ngTabList]", ["ngTabList"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "focusMode": { "alias": "focusMode"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selectedTabIndex": { "alias": "selectedTabIndex"; "required": false; "isSignal": true; }; }, { "selectedTabIndex": "selectedTabIndexChange"; }, ["_tabs"], never, true, never>;
     // (undocumented)
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TabList, never>;
 }
 
 // @public
-export class TabPanel implements OnInit, OnDestroy {
+export class TabPanel {
     constructor();
     readonly element: HTMLElement;
     readonly id: _angular_core.InputSignal<string>;
-    // (undocumented)
-    ngOnDestroy(): void;
-    // (undocumented)
-    ngOnInit(): void;
     readonly _pattern: TabPanelPattern;
-    readonly value: _angular_core.InputSignal<string>;
+    _tabPattern?: TabPattern;
     readonly visible: _angular_core.Signal<boolean>;
     // (undocumented)
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TabPanel, "[ngTabPanel]", ["ngTabPanel"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TabPanel, "[ngTabPanel]", ["ngTabPanel"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
     // (undocumented)
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TabPanel, never>;
 }
 
-// @public
-export class Tabs {
-    readonly element: HTMLElement;
-    // (undocumented)
-    _register(child: TabList | TabPanel): void;
-    readonly _tabPatterns: _angular_core.Signal<TabPattern[] | undefined>;
-    readonly _unorderedTabpanelPatterns: _angular_core.Signal<TabPanelPattern[]>;
-    // (undocumented)
-    _unregister(child: TabList | TabPanel): void;
-    // (undocumented)
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Tabs, "[ngTabs]", ["ngTabs"], {}, {}, never, never, true, never>;
-    // (undocumented)
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<Tabs, never>;
-}
-
 // (No @packageDocumentation comment for this package)
 
 ```

src/aria/private/tabs/tabs.spec.ts

@@ -65,6 +65,7 @@ describe('Tabs Pattern', () => {
       softDisabled: signal(true),
       items: signal([]),
       element: signal(document.createElement('div')),
+      selectedTab: signal(undefined),
     };
     tabListPattern = new TabListPattern(tabListInputs);
 
@@ -76,26 +77,20 @@ describe('Tabs Pattern', () => {
         id: signal('tab-1-id'),
         element: signal(createTabElement()),
         disabled: signal(false),
-        value: signal('tab-1'),
-        expanded: signal(false),
       },
       {
         tablist: signal(tabListPattern),
         tabpanel: signal(undefined),
         id: signal('tab-2-id'),
         element: signal(createTabElement()),
         disabled: signal(false),
-        value: signal('tab-2'),
-        expanded: signal(false),
       },
       {
         tablist: signal(tabListPattern),
         tabpanel: signal(undefined),
         id: signal('tab-3-id'),
         element: signal(createTabElement()),
         disabled: signal(false),
-        value: signal('tab-3'),
-        expanded: signal(false),
       },
     ];
     tabPatterns = [
@@ -109,17 +104,14 @@ describe('Tabs Pattern', () => {
       {
         id: signal('tabpanel-1-id'),
         tab: signal(undefined),
-        value: signal('tab-1'),
       },
       {
         id: signal('tabpanel-2-id'),
         tab: signal(undefined),
-        value: signal('tab-2'),
       },
       {
         id: signal('tabpanel-3-id'),
         tab: signal(undefined),
-        value: signal('tab-3'),
       },
     ];
     tabPanelPatterns = [
@@ -143,8 +135,8 @@ describe('Tabs Pattern', () => {
     describe('#open', () => {
       it('should open a tab with value', () => {
         expect(tabListPattern.selectedTab()).toBeUndefined();
-        tabListPattern.open('tab-1');
-        expect(tabListPattern.selectedTab()!.value()).toBe('tab-1');
+        tabListPattern.open(tabPatterns[0]);
+        expect(tabListPattern.selectedTab()!).toBe(tabPatterns[0]);
       });
 
       it('should open a tab with tab pattern instance', () => {

src/aria/private/tabs/tabs.ts

@@ -7,32 +7,29 @@
  */
 
 import {KeyboardEventManager, PointerEventManager} from '../behaviors/event-manager';
-import {ExpansionItem, ListExpansionInputs, ListExpansion} from '../behaviors/expansion/expansion';
+import {ExpansionItem, ListExpansion, ListExpansionInputs} from '../behaviors/expansion/expansion';
 import {
   SignalLike,
-  computed,
-  signal,
   WritableSignalLike,
+  computed,
+  linkedSignal,
 } from '../behaviors/signal-like/signal-like';
 import {LabelControl, LabelControlOptionalInputs} from '../behaviors/label/label';
 import {ListFocus} from '../behaviors/list-focus/list-focus';
 import {
-  ListNavigationItem,
   ListNavigation,
   ListNavigationInputs,
+  ListNavigationItem,
 } from '../behaviors/list-navigation/list-navigation';
 
 /** The required inputs to tabs. */
 export interface TabInputs
-  extends Omit<ListNavigationItem, 'index'>, Omit<ExpansionItem, 'expandable'> {
+  extends Omit<ListNavigationItem, 'index'>, Omit<ExpansionItem, 'expandable' | 'expanded'> {
   /** The parent tablist that controls the tab. */
   tablist: SignalLike<TabListPattern>;
 
   /** The remote tabpanel controlled by the tab. */
   tabpanel: SignalLike<TabPanelPattern | undefined>;
-
-  /** The remote tabpanel unique identifier. */
-  value: SignalLike<string>;
 }
 
 /** A tab in a tablist. */
@@ -43,9 +40,6 @@ export class TabPattern {
   /** The index of the tab. */
   readonly index = computed(() => this.inputs.tablist().inputs.items().indexOf(this));
 
-  /** The remote tabpanel unique identifier. */
-  readonly value: SignalLike<string> = () => this.inputs.value();
-
   /** Whether the tab is disabled. */
   readonly disabled: SignalLike<boolean> = () => this.inputs.disabled();
 
@@ -55,8 +49,15 @@ export class TabPattern {
   /** Whether this tab has expandable panel. */
   readonly expandable: SignalLike<boolean> = () => true;
 
-  /** Whether the tab panel is expanded. */
-  readonly expanded: WritableSignalLike<boolean>;
+  /*
+   * Whether the tab panel is expanded.
+   * Primarily controlled by the behavior, which will read/write this value.
+   * The consumer of this pattern will instead only use the selectedTab input.
+   * The pattern will be responsible for synchronizing their state.
+   */
+  readonly expanded: WritableSignalLike<boolean> = linkedSignal(
+    () => this.inputs.tablist().selectedTab() === this,
+  );
 
   /** Whether the tab is active. */
   readonly active = computed(() => this.inputs.tablist().inputs.activeItem() === this);
@@ -70,9 +71,7 @@ export class TabPattern {
   /** The id of the tabpanel associated with the tab. */
   readonly controls = computed(() => this.inputs.tabpanel()?.id());
 
-  constructor(readonly inputs: TabInputs) {
-    this.expanded = inputs.expanded;
-  }
+  constructor(readonly inputs: TabInputs) {}
 
   /** Opens the tab. */
   open(): boolean {
@@ -87,19 +86,13 @@ export interface TabPanelInputs extends LabelControlOptionalInputs {
 
   /** The tab that controls this tabpanel. */
   tab: SignalLike<TabPattern | undefined>;
-
-  /** A local unique identifier for the tabpanel. */
-  value: SignalLike<string>;
 }
 
 /** A tabpanel associated with a tab. */
 export class TabPanelPattern {
   /** A global unique identifier for the tabpanel. */
   readonly id: SignalLike<string> = () => this.inputs.id();
 
-  /** A local unique identifier for the tabpanel. */
-  readonly value: SignalLike<string> = () => this.inputs.value();
-
   /** Controls label for this tabpanel. */
   readonly labelManager: LabelControl;
 
@@ -131,6 +124,9 @@ export interface TabListInputs
     Omit<ListExpansionInputs, 'multiExpandable' | 'items'> {
   /** The selection strategy used by the tablist. */
   selectionMode: SignalLike<'follow' | 'explicit'>;
+
+  /** The currently selected tab. */
+  selectedTab: WritableSignalLike<TabPattern | undefined>;
 }
 
 /** Controls the state of a tablist. */
@@ -148,7 +144,7 @@ export class TabListPattern {
   readonly activeTab: SignalLike<TabPattern | undefined> = () => this.inputs.activeItem();
 
   /** The currently selected tab. */
-  readonly selectedTab: WritableSignalLike<TabPattern | undefined> = signal(undefined);
+  readonly selectedTab: WritableSignalLike<TabPattern | undefined>;
 
   /** Whether the tablist is vertically or horizontally oriented. */
   readonly orientation: SignalLike<'vertical' | 'horizontal'> = () => this.inputs.orientation();
@@ -208,6 +204,8 @@ export class TabListPattern {
   });
 
   constructor(readonly inputs: TabListInputs) {
+    this.selectedTab = inputs.selectedTab;
+
     this.focusBehavior = new ListFocus(inputs);
 
     this.navigationBehavior = new ListNavigation({
@@ -263,19 +261,11 @@ export class TabListPattern {
     }
   }
 
-  /** Opens the tab by given value. */
-  open(value: string): boolean;
-
   /** Opens the given tab or the current active tab. */
   open(tab?: TabPattern): boolean;
-
-  open(tab: TabPattern | string | undefined): boolean {
+  open(tab: TabPattern | undefined): boolean {
     tab ??= this.activeTab();
 
-    if (typeof tab === 'string') {
-      tab = this.inputs.items().find(t => t.value() === tab);
-    }
-
     if (tab === undefined) return false;
 
     const success = this.expansionBehavior.open(tab);

src/aria/tabs/public-api.ts

@@ -6,7 +6,6 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-export {Tabs} from './tabs';
 export {TabList} from './tab-list';
 export {Tab} from './tab';
 export {TabPanel} from './tab-panel';