Add ability to mark items as being in preview (#272)

blackbaud · Feb 29, 2024 · 7c0ffe1 · 7c0ffe1
1 parent b8ca070
commit 7c0ffe1
Show file tree

Hide file tree

Showing 40 changed files with 2,109 additions and 127 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## 9.2.0 (2023-02-27)
+
+- Add ability to mark features as being in preview. [#272](https://github.com/blackbaud/skyux-docs-tools/pull/272)
+
 ## 10.0.0-alpha.0 (2024-01-30)
 
 ### ⚠ BREAKING CHANGES

diff --git a/projects/docs-tools/src/modules/demo-page/demo-page.component.html b/projects/docs-tools/src/modules/demo-page/demo-page.component.html
@@ -8,6 +8,22 @@
   >
     <ng-content select="sky-docs-demo-page-summary"></ng-content>
 
+    <sky-alert
+      *ngIf="
+        moduleTypeDefinitions?.hasPreviewFeatures ||
+        testingTypeDefinitions?.hasPreviewFeatures
+      "
+      class="sky-docs-demo-page-preview-alert sky-margin-stacked-lg"
+      >This component currently has preview features available that may not be
+      fully represented in the design documentation, the demo, or code examples.
+      <ng-container *ngIf="siteOptions?.previewFeaturesUrl"
+        >Learn more about this work
+        <a [skyAppLink]="siteOptions?.previewFeaturesUrl"
+          >here.</a
+        ></ng-container
+      ></sky-alert
+    >
+
     <ng-content select="sky-docs-demo"></ng-content>
 
     <div class="sky-docs-demo-page-main">

diff --git a/projects/docs-tools/src/modules/demo-page/demo-page.component.spec.ts b/projects/docs-tools/src/modules/demo-page/demo-page.component.spec.ts
@@ -19,6 +19,16 @@ import { SkyDocsTypeDefinitionsService } from '../type-definitions/type-definiti
 import { MockTypeDocAdapterService } from '../type-definitions/fixtures/mock-type-definitions.service';
 import { SkyDocsTypeDocAdapterService } from '../type-definitions/typedoc-adapter.service';
 import { TypeDocKind } from '../type-definitions/typedoc-types';
+import { SkyDocsToolsSiteOptions } from '../shared/docs-tools-site-options';
+
+function getPreviewAlert(): HTMLElement | null {
+  return document.querySelector('.sky-docs-demo-page-preview-alert');
+}
+
+function getPreviewAlertLink(): HTMLAnchorElement | null {
+  return getPreviewAlert().querySelector('a');
+}
+
 function getService(
   provider: SkyDocsTypeDefinitionsProvider = {
     anchorIds: {},
@@ -181,7 +191,7 @@ describe('Demo page component', () => {
   let component: DemoPageFixtureComponent;
   let mockMediaQueryService: MockSkyMediaQueryService;
 
-  beforeEach(() => {
+  function setupTestBed(): void {
     mockMediaQueryService = new MockSkyMediaQueryService();
     TestBed.configureTestingModule({
       imports: [DemoPageFixturesModule],
@@ -191,8 +201,25 @@ describe('Demo page component', () => {
           useValue: mockMediaQueryService,
         },
         { provide: SkyDocsTypeDefinitionsService, useValue: getService() },
+        {
+          provide: SkyDocsTypeDefinitionsProvider,
+          useValue: {
+            anchorIds: {
+              FooUser: 'foo-user',
+            },
+            typeDefinitions: [
+              {
+                name: 'FooUser',
+              },
+            ],
+          },
+        },
       ],
     });
+  }
+
+  beforeEach(() => {
+    setupTestBed();
 
     fixture = TestBed.createComponent(DemoPageFixtureComponent);
     component = fixture.componentInstance;
@@ -321,4 +348,54 @@ describe('Demo page component', () => {
     );
     expect(sidebarLinks[1].getAttribute('href')).toEqual('/bar');
   });
+
+  it('should not show the preview features alert if there are no preview features', () => {
+    fixture.detectChanges();
+    const previewAlert = getPreviewAlert();
+    expect(previewAlert).toBeNull();
+  });
+
+  it('should show the preview features alert if there are preview features - no link', () => {
+    spyOn(
+      MockTypeDocAdapterService.prototype,
+      'toClassDefinition'
+    ).and.callFake((entry) => {
+      return {
+        hasPreviewFeatures: true,
+        anchorId: entry.anchorId,
+        name: entry.name,
+      };
+    });
+    fixture.detectChanges();
+    const previewAlert = getPreviewAlert();
+    const previewAlertLink = getPreviewAlertLink();
+    expect(previewAlert).not.toBeNull();
+    expect(previewAlertLink).toBeNull();
+  });
+
+  it('should show the preview features alert if there are preview features - with a link when provided by the consumer', () => {
+    TestBed.resetTestingModule();
+    TestBed.overrideProvider(SkyDocsToolsSiteOptions, {
+      useValue: { previewFeaturesUrl: 'www.blackbaud.com' },
+    });
+    setupTestBed();
+
+    fixture = TestBed.createComponent(DemoPageFixtureComponent);
+    component = fixture.componentInstance;
+    spyOn(
+      MockTypeDocAdapterService.prototype,
+      'toClassDefinition'
+    ).and.callFake((entry) => {
+      return {
+        hasPreviewFeatures: true,
+        anchorId: entry.anchorId,
+        name: entry.name,
+      };
+    });
+    fixture.detectChanges();
+    const previewAlert = getPreviewAlert();
+    const previewAlertLink = getPreviewAlertLink();
+    expect(previewAlert).not.toBeNull();
+    expect(previewAlertLink).not.toBeNull();
+  });
 });
diff --git a/projects/docs-tools/src/modules/demo-page/demo-page.component.ts b/projects/docs-tools/src/modules/demo-page/demo-page.component.ts
@@ -9,6 +9,7 @@ import {
   Input,
   OnInit,
   QueryList,
+  inject,
 } from '@angular/core';
 
 import { ActivatedRoute, Router } from '@angular/router';
@@ -30,6 +31,7 @@ import { SkyDocsDemoPageDomAdapterService } from './demo-page-dom-adapter.servic
 import { SkyDocsDemoPageTitleService } from './demo-page-title.service';
 import { SkyDocsTypeDefinitionsService } from '../type-definitions/type-definitions.service';
 import { SkyDocsTypeDefinitions } from '../type-definitions/type-definitions';
+import { SkyDocsToolsSiteOptions } from '../shared/docs-tools-site-options';
 
 /**
  * The demo page component wraps all documentation components and handles the configuration and layout of the page.
@@ -161,12 +163,19 @@ export class SkyDocsDemoPageComponent
    */
   public sidebarRoutes: StacheNavLink[];
 
+  protected hasPreviewFeatures = false;
+
   @ContentChild(SkyDocsDesignGuidelinesComponent)
   private designGuidelinesComponent: SkyDocsDesignGuidelinesComponent;
 
   @ContentChildren(SkyDocsCodeExamplesComponent)
   private codeExampleComponents: QueryList<SkyDocsCodeExamplesComponent>;
 
+  protected readonly siteOptions: SkyDocsToolsSiteOptions | undefined = inject(
+    SkyDocsToolsSiteOptions,
+    { optional: true }
+  );
+
   #_additionalSourceCodePaths: string[] | undefined;
   #_additionalTestingSourceCodePaths: string[] | undefined;
   #_moduleSourceCodePath: string | undefined;

diff --git a/projects/docs-tools/src/modules/demo-page/demo-page.module.ts b/projects/docs-tools/src/modules/demo-page/demo-page.module.ts
@@ -35,11 +35,15 @@ import { SkyDocsDemoPageComponent } from './demo-page.component';
 import { SkyDocsDemoPageModuleInfoComponent } from './demo-page-module-info.component';
 
 import { SkyDocsDemoPageTypeDefinitionsComponent } from './demo-page-type-definitions.component';
+import { SkyAlertModule } from '@skyux/indicators';
+import { SkyAppLinkModule } from '@skyux/router';
 
 @NgModule({
   imports: [
     CommonModule,
     RouterModule,
+    SkyAlertModule,
+    SkyAppLinkModule,
     SkyCodeBlockModule,
     SkyCodeModule,
     SkyDocsDemoModule,

diff --git a/projects/docs-tools/src/modules/demo-page/fixtures/demo-page-fixtures.module.ts b/projects/docs-tools/src/modules/demo-page/fixtures/demo-page-fixtures.module.ts
@@ -35,6 +35,9 @@ class MockSkyAppConfig {
       base: '/demo-test-base/',
     },
     routes: [],
+    params: {
+      getAll: (_: unknown) => {},
+    },
   };
 
   public skyux: any = {

diff --git a/projects/docs-tools/src/modules/shared/docs-tools-site-options.ts b/projects/docs-tools/src/modules/shared/docs-tools-site-options.ts
@@ -0,0 +1,3 @@
+export class SkyDocsToolsSiteOptions {
+  public previewFeaturesUrl: string;
+}
diff --git a/projects/docs-tools/src/modules/type-definitions/class-definition.component.spec.ts b/projects/docs-tools/src/modules/type-definitions/class-definition.component.spec.ts
@@ -54,6 +54,7 @@ describe('Class definition component', function () {
       anchorId: 'service-fooservice',
       description: 'This description has a FooUser.',
       name: 'FooService',
+      hasPreviewFeatures: false,
     };
 
     fixture.detectChanges();

diff --git a/projects/docs-tools/src/modules/type-definitions/class-definition.ts b/projects/docs-tools/src/modules/type-definitions/class-definition.ts
@@ -8,6 +8,8 @@ import { SkyDocsClassMethodDefinition } from './method-definition';
  * Describes classes and services.
  */
 export interface SkyDocsClassDefinition extends SkyDocsEntryDefinition {
+  hasPreviewFeatures: boolean;
+
   methods?: SkyDocsClassMethodDefinition[];
 
   properties?: SkyDocsClassPropertyDefinition[];

diff --git a/projects/docs-tools/src/modules/type-definitions/directive-definition.component.spec.ts b/projects/docs-tools/src/modules/type-definitions/directive-definition.component.spec.ts
@@ -61,6 +61,7 @@ describe('Directive definition component', function () {
       anchorId: 'foo-anchor-id',
       name: 'FooComponent',
       selector: 'app-foo',
+      hasPreviewFeatures: false,
     };
 
     fixture.detectChanges();
@@ -77,13 +78,15 @@ describe('Directive definition component', function () {
       anchorId: 'foo-anchor-id',
       name: 'FooComponent',
       selector: 'app-foo',
+      hasPreviewFeatures: false,
       inputProperties: [
         {
           name: 'config',
           decorator: {
             name: 'Input',
           },
           isOptional: true,
+          isPreview: false,
           type: {
             type: 'reference',
             name: 'Config',
@@ -97,6 +100,7 @@ describe('Directive definition component', function () {
             name: 'Output',
           },
           isOptional: true,
+          isPreview: false,
           type: {
             type: 'reference',
             name: 'EventEmitter',
@@ -130,13 +134,15 @@ describe('Directive definition component', function () {
       anchorId: 'foo-anchor-id',
       name: 'FooComponent',
       selector: 'app-foo',
+      hasPreviewFeatures: false,
       eventProperties: [
         {
           name: 'click',
           decorator: {
             name: 'Output',
           },
           isOptional: false,
+          isPreview: false,
           type: {},
         },
       ],
@@ -156,6 +162,7 @@ describe('Directive definition component', function () {
       anchorId: 'component-foocomponent',
       name: 'FooComponent',
       description: 'This description has a [[FooUser]].',
+      hasPreviewFeatures: false,
       selector: 'app-foo',
     };
 

diff --git a/projects/docs-tools/src/modules/type-definitions/directive-definition.ts b/projects/docs-tools/src/modules/type-definitions/directive-definition.ts
@@ -8,6 +8,8 @@ import { SkyDocsEntryDefinition } from './entry-definition';
 export interface SkyDocsDirectiveDefinition extends SkyDocsEntryDefinition {
   eventProperties?: SkyDocsClassPropertyDefinition[];
 
+  hasPreviewFeatures: boolean;
+
   inputProperties?: SkyDocsClassPropertyDefinition[];
 
   selector: string;

diff --git a/projects/docs-tools/src/modules/type-definitions/enumeration-definition.component.spec.ts b/projects/docs-tools/src/modules/type-definitions/enumeration-definition.component.spec.ts
@@ -66,9 +66,11 @@ describe('Enumeration definition component', function () {
       anchorId: 'foo-anchor-id',
       name: 'Foo',
       description: 'This description has a FooUser.',
+      hasPreviewFeatures: false,
       members: [
         {
           name: 'Bar',
+          isPreview: false,
         },
       ],
     };
@@ -90,9 +92,11 @@ describe('Enumeration definition component', function () {
       anchorId: 'foo-anchor-id',
       name: 'Foo',
       description: 'This description has a `Date`.',
+      hasPreviewFeatures: false,
       members: [
         {
           name: 'Bar',
+          isPreview: false,
         },
       ],
     };
@@ -112,10 +116,12 @@ describe('Enumeration definition component', function () {
       anchorId: 'foo-anchor-id',
       name: 'Foo',
       description: '',
+      hasPreviewFeatures: false,
       members: [
         {
           description: 'This description has a FooUser.',
           name: 'Bar',
+          isPreview: false,
         },
       ],
     };

diff --git a/projects/docs-tools/src/modules/type-definitions/enumeration-definition.ts b/projects/docs-tools/src/modules/type-definitions/enumeration-definition.ts
@@ -6,5 +6,6 @@ import { SkyDocsEnumerationMemberDefinition } from './enumeration-member-definit
  * Describes enumerations.
  */
 export interface SkyDocsEnumerationDefinition extends SkyDocsEntryDefinition {
+  hasPreviewFeatures: boolean;
   members: SkyDocsEnumerationMemberDefinition[];
 }
diff --git a/projects/docs-tools/src/modules/type-definitions/enumeration-member-definition.ts b/projects/docs-tools/src/modules/type-definitions/enumeration-member-definition.ts
@@ -10,5 +10,7 @@ export interface SkyDocsEnumerationMemberDefinition {
 
   description?: string;
 
+  isPreview: boolean;
+
   name: string;
 }