feat(daffio): render subpackages on package page (#3094)

---------

Co-authored-by: xelaint <xelaint@gmail.com>

apps/daffio/src/app/docs/api/components/api-list-section/api-list-section.component.scss

@@ -41,7 +41,7 @@ $api-list-section-item-border-radius: 4px;
 			top: 0;
 			height: 100%;
 			width: 100%;
-			transition: opacity 300ms;
+			transition: opacity 150ms;
 			z-index: 1;
 		}
 

apps/daffio/src/app/docs/api/components/api-list/api-list.component.scss

@@ -32,7 +32,7 @@
 			@include daff.text-truncate();
 
 			@include daff.breakpoint(mobile) {
-				display: inline-block;
+				display: inline;
 			}
 		}
 	}

apps/daffio/src/app/docs/api/components/api-package/api-package-theme.scss

@@ -0,0 +1,23 @@
+@use 'theme' as daff-theme;
+
+@mixin daffio-api-package-theme($theme) {
+	$neutral: daff-theme.daff-map-deep-get($theme, 'core.neutral');
+	$base: daff-theme.daff-map-deep-get($theme, "core.base");
+	$base-contrast: daff-theme.daff-map-deep-get($theme, "core.base-contrast");
+
+	.daffio-api-package {
+		&__subpackage-name {
+			> * {
+				&:focus {
+					border-radius: 4px;
+					box-shadow: 0 0 0 4px rgba($base-contrast, 0.1);
+					outline: none;
+				}
+			}
+
+			&:hover {
+				color: daff-theme.daff-illuminate($base-contrast, $neutral, 3);
+			}
+		}
+	}
+}

apps/daffio/src/app/docs/api/components/api-package/api-package.component.html

@@ -0,0 +1,16 @@
+<div class="daffio-api-package__wrapper">
+  <div class="daffio-api-package__header">
+    <h1 class="daffio-api-package__package-name">{{doc.title}}</h1>
+    <p *ngIf="doc.description" class="daffio-api-package__package-description">{{doc.description}}</p>
+  </div>
+  <daffio-api-list-section [children]="doc.children | apiPackageFilter:true" class="daffio-doc-viewer__api-section"></daffio-api-list-section>
+</div>
+
+@for (package of doc.children | apiPackageFilter; track package.id) {
+  <div class="daffio-api-package__wrapper">
+    <h2 class="daffio-api-package__subpackage-name">
+      <a [routerLink]="package.path">{{package.title}}</a>
+    </h2>
+    <daffio-api-list-section [children]="package.children | apiPackageFilter:true" class="daffio-doc-viewer__api-section" [attr.data-section-for-subpackage]="package.id"></daffio-api-list-section>
+  </div>
+}

apps/daffio/src/app/docs/api/components/api-package/api-package.component.scss

@@ -0,0 +1,64 @@
+@use '../../../../../scss/type-descriptors/mixins' as type-mixin;
+@use 'utilities' as daff;
+
+:host {
+	display: flex;
+	flex-direction: column;
+	gap: 48px;
+
+	a {
+		text-decoration: none;
+	}
+}
+
+.daffio-api-package {
+	&__wrapper {
+		display: flex;
+		flex-direction: column;
+		gap: 24px;
+	}
+
+	&__header {
+		display: flex;
+		flex-direction: column;
+		gap: 16px;
+	}
+
+	&__package-name {
+		@include daff.headline-lg;
+
+		> * {
+			@include daff.text-truncate();
+
+			@include daff.breakpoint(mobile) {
+				display: inline;
+			}
+		}
+	}
+
+	&__package-description {
+		@include daff.body-md;
+		font-weight: 400;
+		margin: 0;
+		padding: 0;
+	}
+
+	&__subpackage-name {
+		font-size: 1.125rem;
+		font-weight: 600;
+		line-height: 1.375rem;
+
+		@include daff.breakpoint(mobile) {
+			font-size: 1.25rem;
+			line-height: 1.75rem;
+		}
+
+		> * {
+			@include daff.text-truncate();
+
+			@include daff.breakpoint(mobile) {
+				display: inline-block;
+			}
+		}
+	}
+}

apps/daffio/src/app/docs/api/components/api-package/api-package.component.spec.ts

@@ -0,0 +1,128 @@
+import {
+  Component,
+  DebugElement,
+} from '@angular/core';
+import {
+  ComponentFixture,
+  TestBed,
+  waitForAsync,
+} from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+import { RouterTestingModule } from '@angular/router/testing';
+
+import { DaffioApiPackageComponent } from './api-package.component';
+import { DaffioApiReference } from '../../models/api-reference';
+import { DaffioApiListSectionComponent } from '../api-list-section/api-list-section.component';
+
+@Component({
+  template: `
+    <daffio-api-package [doc]="apiListValue"></daffio-api-package>
+  `,
+  standalone: true,
+  imports: [
+    DaffioApiPackageComponent,
+  ],
+})
+class WrapperComponent {
+  apiListValue: DaffioApiReference;
+}
+
+describe('DaffioApiPackageComponent', () => {
+  let wrapper: WrapperComponent;
+  let fixture: ComponentFixture<WrapperComponent>;
+  let component: DaffioApiPackageComponent;
+  let packageLinks: Array<DebugElement>;
+
+  beforeEach(waitForAsync(() => {
+    TestBed.configureTestingModule({
+      imports: [
+        WrapperComponent,
+        RouterTestingModule,
+      ],
+    })
+      .compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(WrapperComponent);
+    wrapper = fixture.componentInstance;
+    wrapper.apiListValue = {
+      id: 'Root',
+      path: 'path',
+      docType: 'package',
+      docTypeShorthand: 'pk',
+      title: 'title',
+      description: 'description',
+      children: [
+        {
+          id: 'name1Component',
+          title: 'title1Component',
+          path: 'path1',
+          docType: 'docType1',
+          docTypeShorthand: 'dt',
+          children: [],
+        },
+        {
+          id: 'name2Module',
+          title: 'title2Module',
+          path: 'path2',
+          docType: 'package',
+          docTypeShorthand: 'pk',
+          children: [
+            {
+              id: 'name1Component',
+              title: 'title1Component',
+              path: 'path1',
+              docType: 'docType1',
+              docTypeShorthand: 'dt',
+              children: [],
+            },
+            {
+              id: 'name2Module',
+              title: 'title2Module',
+              path: 'path2',
+              docType: 'package',
+              docTypeShorthand: 'pk',
+              children: [],
+            },
+          ],
+        },
+      ],
+    };
+    fixture.detectChanges();
+
+    component = fixture.debugElement.query(By.css('daffio-api-package')).componentInstance;
+    packageLinks = fixture.debugElement.queryAll(By.css('a.daffio-api-package__package-name'));
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+
+  it('should be able to take doc as input', () => {
+    expect(component.doc).toEqual(wrapper.apiListValue);
+  });
+
+  describe('for every subpackage in children', () => {
+    let subpackages: Array<DaffioApiReference>;
+
+    beforeEach(() => {
+      subpackages = wrapper.apiListValue.children.filter((d) => d.docType === 'package');
+    });
+
+    it('should render a link with the title', () => {
+      packageLinks.forEach((de, i) => {
+        expect(de.nativeElement.innerText).toEqual(subpackages[i].title);
+        expect(de.attributes['ng-reflect-router-link']).toEqual(subpackages[i].path);
+      });
+    });
+
+    it('should render an API section with the subpackage children excluding packages', () => {
+      packageLinks.forEach((de, i) => {
+        const apiSection: DaffioApiListSectionComponent = fixture.debugElement.query(By.css(`daffio-api-list-section[data-section-for-subpackage="${subpackages[i].id}"]`)).componentInstance;
+        expect(apiSection.children).toEqual(subpackages[i].children.filter((c) => c.docType !== 'package'));
+      });
+    });
+  });
+
+});

apps/daffio/src/app/docs/api/components/api-package/api-package.component.ts

@@ -0,0 +1,39 @@
+import {
+  Component,
+  Input,
+  ChangeDetectionStrategy,
+  HostBinding,
+} from '@angular/core';
+import { RouterLink } from '@angular/router';
+
+import { DaffArticleEncapsulatedDirective } from '@daffodil/design';
+import { DaffArticleModule } from '@daffodil/design/article';
+
+import { DaffioApiPackageFilterPipe } from './not-packages.pipe';
+import { DaffioApiReference } from '../../models/api-reference';
+import { DaffioApiListSectionComponent } from '../api-list-section/api-list-section.component';
+
+@Component({
+  selector: 'daffio-api-package',
+  templateUrl: './api-package.component.html',
+  styleUrls: ['./api-package.component.scss'],
+  hostDirectives: [{
+    directive: DaffArticleEncapsulatedDirective,
+  }],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [
+    RouterLink,
+    DaffioApiListSectionComponent,
+    DaffArticleModule,
+    DaffioApiPackageFilterPipe,
+  ],
+})
+export class DaffioApiPackageComponent {
+  @HostBinding('class.daffio-api-package') class = true;
+
+  /**
+   * A list of references for API documents.
+   */
+  @Input() doc: DaffioApiReference;
+}

apps/daffio/src/app/docs/api/components/api-package/not-packages.pipe.ts

@@ -0,0 +1,23 @@
+import {
+  Pipe,
+  PipeTransform,
+} from '@angular/core';
+
+import { DaffioApiReference } from '../../models/api-reference';
+
+/**
+ * Filters packages from a list of API docs.
+ * If exclude is false or omitted, will only output packages.
+ * Otherwise it will omit packages from the output.
+ */
+@Pipe({
+  name: 'apiPackageFilter',
+  standalone: true,
+})
+export class DaffioApiPackageFilterPipe implements PipeTransform {
+  transform(docs: Array<DaffioApiReference>, exclude = false) {
+    return exclude
+      ? docs.filter((doc) => doc.docType !== 'package')
+      : docs.filter((doc) => doc.docType === 'package');
+  }
+}

apps/daffio/src/app/docs/api/models/api-reference.ts

@@ -6,4 +6,5 @@ import { DaffioGenericDocList } from '../../models/doc-list';
 export interface DaffioApiReference extends DaffioGenericDocList<DaffioApiReference> {
   docType: string;
   docTypeShorthand: string;
+  description?: string;
 }

apps/daffio/src/app/docs/components/doc-viewer/doc-viewer.component.html

@@ -4,11 +4,7 @@
 </button>
 <div class="daffio-doc-viewer__grid">
   @if (isApiPackage) {
-    <daff-article class="daffio-doc-viewer__content">
-      <h1>{{doc.title}}</h1>
-      <p>{{doc.description}}</p>
-	    <daffio-api-list-section [children]="doc.children" class="daffio-doc-viewer__api-section"></daffio-api-list-section>
-    </daff-article>
+    <daffio-api-package [doc]="doc"></daffio-api-package>
   } @else {
     <daff-article
       class="daffio-doc-viewer__content"

apps/daffio/src/app/docs/components/doc-viewer/doc-viewer.component.spec.ts

@@ -11,7 +11,7 @@ import { provideMockStore } from '@ngrx/store/testing';
 import { DaffArticleModule } from '@daffodil/design/article';
 
 import { DaffioDocViewerComponent } from './doc-viewer.component';
-import { DaffioApiListSectionComponent } from '../../api/components/api-list-section/api-list-section.component';
+import { DaffioApiPackageComponent } from '../../api/components/api-package/api-package.component';
 import { DaffioApiReference } from '../../api/models/api-reference';
 import { DaffioDoc } from '../../models/doc';
 import { DaffioDocsFactory } from '../../testing/factories/docs.factory';
@@ -35,7 +35,7 @@ describe('DaffioDocViewerComponent', () => {
         RouterTestingModule,
         DaffArticleModule,
         DaffioDocsTableOfContentsModule,
-        DaffioApiListSectionComponent,
+        DaffioApiPackageComponent,
       ],
       declarations: [
         WrapperComponent,
@@ -81,13 +81,9 @@ describe('DaffioDocViewerComponent', () => {
       fixture.detectChanges();
     });
 
-    it('should render the package name', () => {
-      expect(fixture.debugElement.query(By.css('.daffio-doc-viewer__content h1')).nativeElement.innerText).toEqual(wrapper.doc.title);
-    });
-
-    it('should render the package doc children', () => {
-      const apiChildren: DaffioApiListSectionComponent = fixture.debugElement.query(By.directive(DaffioApiListSectionComponent)).componentInstance;
-      expect(apiChildren.children).toEqual((<DaffioApiReference>wrapper.doc).children);
+    it('should render the package doc', () => {
+      const apiChildren: DaffioApiPackageComponent = fixture.debugElement.query(By.directive(DaffioApiPackageComponent)).componentInstance;
+      expect(apiChildren.doc).toEqual((<DaffioApiReference>wrapper.doc));
     });
   });
 

apps/daffio/src/app/docs/components/doc-viewer/doc-viewer.module.ts

@@ -8,7 +8,7 @@ import { DaffContainerModule } from '@daffodil/design/container';
 import { DaffSidebarModule } from '@daffodil/design/sidebar';
 
 import { DaffioDocViewerComponent } from './doc-viewer.component';
-import { DaffioApiListSectionComponent } from '../../api/components/api-list-section/api-list-section.component';
+import { DaffioApiPackageComponent } from '../../api/components/api-package/api-package.component';
 import { DaffioDocsTableOfContentsModule } from '../table-of-contents/table-of-contents.module';
 
 @NgModule({
@@ -23,7 +23,7 @@ import { DaffioDocsTableOfContentsModule } from '../table-of-contents/table-of-c
     DaffArticleModule,
     DaffContainerModule,
     DaffioDocsTableOfContentsModule,
-    DaffioApiListSectionComponent,
+    DaffioApiPackageComponent,
     DaffSidebarModule,
     DaffButtonModule,
     FontAwesomeModule,