refactor(aria/tabs): split directives and resolve circular dependencies

Splits up the directives across files and resolve circular dependencies in them.

Author: crisbeto

goldens/aria/tabs/index.api.md

@@ -61,7 +61,7 @@ export class TabList implements OnInit, OnDestroy {
     readonly selectedTab: _angular_core.ModelSignal<string | undefined>;
     readonly selectionMode: _angular_core.InputSignal<"follow" | "explicit">;
     readonly softDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    readonly _tabPatterns: _angular_core.Signal<TabPattern[]>;
+    readonly _tabPatterns: _angular_core.Signal<i1.TabPattern[]>;
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
     // (undocumented)
     _unregister(child: Tab): void;
@@ -95,8 +95,8 @@ 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[]>;
+    readonly _tabPatterns: _angular_core.Signal<i1.TabPattern[] | undefined>;
+    readonly _unorderedTabpanelPatterns: _angular_core.Signal<i1.TabPanelPattern[]>;
     // (undocumented)
     _unregister(child: TabList | TabPanel): void;
     // (undocumented)

src/aria/tabs/BUILD.bazel

@@ -4,10 +4,10 @@ package(default_visibility = ["//visibility:public"])
 
 ng_project(
     name = "tabs",
-    srcs = [
-        "index.ts",
-        "tabs.ts",
-    ],
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = ["**/*.spec.ts"],
+    ),
     deps = [
         "//:node_modules/@angular/core",
         "//src/aria/private",

src/aria/tabs/index.ts

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

src/aria/tabs/tab-content.ts

@@ -0,0 +1,34 @@
+/**
+ * @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 {Directive} from '@angular/core';
+import {DeferredContent} from '@angular/aria/private';
+
+/**
+ * A TabContent container for the lazy-loaded content.
+ *
+ * This structural directive should be applied to an `ng-template` within an `ngTabPanel`.
+ * It enables lazy loading of the tab's content, meaning the content is only rendered
+ * when the tab is activated for the first time.
+ *
+ * ```html
+ * <div ngTabPanel value="myTabId">
+ *   <ng-template ngTabContent>
+ *     <p>This content will be loaded when 'myTabId' is selected.</p>
+ *   </ng-template>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
+@Directive({
+  selector: 'ng-template[ngTabContent]',
+  exportAs: 'ngTabContent',
+  hostDirectives: [DeferredContent],
+})
+export class TabContent {}

src/aria/tabs/tab-list.ts

@@ -0,0 +1,169 @@
+/**
+ * @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 {Directionality} from '@angular/cdk/bidi';
+import {
+  booleanAttribute,
+  computed,
+  Directive,
+  ElementRef,
+  inject,
+  input,
+  model,
+  signal,
+  afterRenderEffect,
+  OnInit,
+  OnDestroy,
+} from '@angular/core';
+import {TabListPattern} from '@angular/aria/private';
+import {sortDirectives, TABS} from './utils';
+import type {Tab} from './tab';
+
+/**
+ * A TabList container.
+ *
+ * The `ngTabList` directive controls a list of `ngTab` elements. It manages keyboard
+ * navigation, selection, and the overall orientation of the tabs. It should be placed
+ * within an `ngTabs` container.
+ *
+ * ```html
+ * <ul ngTabList [(selectedTab)]="mySelectedTab" orientation="horizontal" selectionMode="explicit">
+ *   <li ngTab value="first">First Tab</li>
+ *   <li ngTab value="second">Second Tab</li>
+ * </ul>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
+@Directive({
+  selector: '[ngTabList]',
+  exportAs: 'ngTabList',
+  host: {
+    'role': 'tablist',
+    '[attr.tabindex]': '_pattern.tabIndex()',
+    '[attr.aria-disabled]': '_pattern.disabled()',
+    '[attr.aria-orientation]': '_pattern.orientation()',
+    '[attr.aria-activedescendant]': '_pattern.activeDescendant()',
+    '(keydown)': '_pattern.onKeydown($event)',
+    '(pointerdown)': '_pattern.onPointerdown($event)',
+    '(focusin)': '_onFocus()',
+  },
+})
+export class TabList implements OnInit, OnDestroy {
+  /** A reference to the host element. */
+  private readonly _elementRef = inject(ElementRef);
+
+  /** A reference to the host element. */
+  readonly element = this._elementRef.nativeElement as HTMLElement;
+
+  /** The parent Tabs. */
+  private readonly _tabs = inject(TABS);
+
+  /** The Tabs nested inside of the TabList. */
+  private readonly _unorderedTabs = signal(new Set<Tab>());
+
+  /** Text direction. */
+  readonly textDirection = inject(Directionality).valueSignal;
+
+  /** The Tab UIPatterns of the child Tabs. */
+  readonly _tabPatterns = computed(() =>
+    [...this._unorderedTabs()].sort(sortDirectives).map(tab => tab._pattern),
+  );
+
+  /** Whether the tablist is vertically or horizontally oriented. */
+  readonly orientation = input<'vertical' | 'horizontal'>('horizontal');
+
+  /** Whether focus should wrap when navigating. */
+  readonly wrap = input(true, {transform: booleanAttribute});
+
+  /**
+   * Whether to allow disabled items to receive focus. When `true`, disabled items are
+   * focusable but not interactive. When `false`, disabled items are skipped during navigation.
+   */
+  readonly softDisabled = input(true, {transform: booleanAttribute});
+
+  /**
+   * The focus strategy used by the tablist.
+   * - `roving`: Focus is moved to the active tab using `tabindex`.
+   * - `activedescendant`: Focus remains on the tablist container, and `aria-activedescendant` is used to indicate the active tab.
+   */
+  readonly focusMode = input<'roving' | 'activedescendant'>('roving');
+
+  /**
+   * The selection strategy used by the tablist.
+   * - `follow`: The focused tab is automatically selected.
+   * - `explicit`: Tabs are selected explicitly by the user (e.g., via click or spacebar).
+   */
+  readonly selectionMode = input<'follow' | 'explicit'>('follow');
+
+  /** The current selected tab. */
+  readonly selectedTab = model<string | undefined>();
+
+  /** Whether the tablist is disabled. */
+  readonly disabled = input(false, {transform: booleanAttribute});
+
+  /** The TabList UIPattern. */
+  readonly _pattern: TabListPattern = new TabListPattern({
+    ...this,
+    items: this._tabPatterns,
+    activeItem: signal(undefined),
+    element: () => this._elementRef.nativeElement,
+  });
+
+  /** Whether the tree has received focus yet. */
+  private _hasFocused = signal(false);
+
+  constructor() {
+    afterRenderEffect(() => {
+      if (!this._hasFocused()) {
+        this._pattern.setDefaultState();
+      }
+    });
+
+    afterRenderEffect(() => {
+      const tab = this._pattern.selectedTab();
+      if (tab) {
+        this.selectedTab.set(tab.value());
+      }
+    });
+
+    afterRenderEffect(() => {
+      const value = this.selectedTab();
+      if (value) {
+        this._pattern.open(value);
+      }
+    });
+  }
+
+  _onFocus() {
+    this._hasFocused.set(true);
+  }
+
+  ngOnInit() {
+    this._tabs._register(this);
+  }
+
+  ngOnDestroy() {
+    this._tabs._unregister(this);
+  }
+
+  _register(child: Tab) {
+    this._unorderedTabs().add(child);
+    this._unorderedTabs.set(new Set(this._unorderedTabs()));
+  }
+
+  _unregister(child: Tab) {
+    this._unorderedTabs().delete(child);
+    this._unorderedTabs.set(new Set(this._unorderedTabs()));
+  }
+
+  /** Opens the tab panel with the specified value. */
+  open(value: string): boolean {
+    return this._pattern.open(value);
+  }
+}

src/aria/tabs/tab-panel.ts

@@ -0,0 +1,101 @@
+/**
+ * @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 {_IdGenerator} from '@angular/cdk/a11y';
+import {
+  computed,
+  Directive,
+  ElementRef,
+  inject,
+  input,
+  afterRenderEffect,
+  OnInit,
+  OnDestroy,
+} from '@angular/core';
+import {TabPanelPattern, DeferredContentAware} from '@angular/aria/private';
+import {TABS} from './utils';
+
+/**
+ * A TabPanel container for the resources of layered content associated with a tab.
+ *
+ * The `ngTabPanel` directive holds the content for a specific tab. It is linked to an
+ * `ngTab` by a matching `value`. If a tab panel is hidden, the `inert` attribute will be
+ * applied to remove it from the accessibility tree. Proper styling is required for visual hiding.
+ *
+ * ```html
+ * <div ngTabPanel value="myTabId">
+ *   <ng-template ngTabContent>
+ *     <!-- Content for the tab panel -->
+ *   </ng-template>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
+@Directive({
+  selector: '[ngTabPanel]',
+  exportAs: 'ngTabPanel',
+  host: {
+    'role': 'tabpanel',
+    '[attr.id]': '_pattern.id()',
+    '[attr.tabindex]': '_pattern.tabIndex()',
+    '[attr.inert]': '!visible() ? true : null',
+    '[attr.aria-labelledby]': '_pattern.labelledBy()',
+  },
+  hostDirectives: [
+    {
+      directive: DeferredContentAware,
+      inputs: ['preserveContent'],
+    },
+  ],
+})
+export class TabPanel implements OnInit, OnDestroy {
+  /** A reference to the host element. */
+  private readonly _elementRef = inject(ElementRef);
+
+  /** A reference to the host element. */
+  readonly element = this._elementRef.nativeElement as HTMLElement;
+
+  /** The DeferredContentAware host directive. */
+  private readonly _deferredContentAware = inject(DeferredContentAware);
+
+  /** The parent Tabs. */
+  private readonly _tabs = inject(TABS);
+
+  /** A global unique identifier for the tab. */
+  readonly id = input(inject(_IdGenerator).getId('ng-tabpanel-', true));
+
+  /** The Tab UIPattern associated with the tabpanel */
+  private readonly _tabPattern = computed(() =>
+    this._tabs._tabPatterns()?.find(tab => tab.value() === this.value()),
+  );
+
+  /** A local unique identifier for the tabpanel. */
+  readonly value = input.required<string>();
+
+  /** Whether the tab panel is visible. */
+  readonly visible = computed(() => !this._pattern.hidden());
+
+  /** The TabPanel UIPattern. */
+  readonly _pattern: TabPanelPattern = new TabPanelPattern({
+    ...this,
+    tab: this._tabPattern,
+  });
+
+  constructor() {
+    afterRenderEffect(() => this._deferredContentAware.contentVisible.set(this.visible()));
+  }
+
+  ngOnInit() {
+    this._tabs._register(this);
+  }
+
+  ngOnDestroy() {
+    this._tabs._unregister(this);
+  }
+}