Add ability to mark items as being in preview

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)
+
 ## 9.1.5 (2023-10-09)
 
 - Allow a demo page to be created without the `moduleName` input. [#268](https://github.com/blackbaud/skyux-docs-tools/pull/268)

projects/docs-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyux/docs-tools",
-  "version": "9.1.5",
+  "version": "9.2.0",
   "peerDependencies": {
     "@angular/common": "^16.2.5",
     "@angular/core": "^16.2.5",

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 inputs 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">

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();
+  });
 });

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;

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,

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 = {

projects/docs-tools/src/modules/shared/docs-tools-site-options.ts

@@ -0,0 +1,3 @@
+export class SkyDocsToolsSiteOptions {
+  public previewFeaturesUrl: string;
+}

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();

projects/docs-tools/src/modules/type-definitions/class-definition.ts

@@ -11,4 +11,6 @@ export interface SkyDocsClassDefinition extends SkyDocsEntryDefinition {
   methods?: SkyDocsClassMethodDefinition[];
 
   properties?: SkyDocsClassPropertyDefinition[];
+
+  hasPreviewFeatures: boolean;
 }

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',
     };
 

projects/docs-tools/src/modules/type-definitions/directive-definition.ts

@@ -11,4 +11,6 @@ export interface SkyDocsDirectiveDefinition extends SkyDocsEntryDefinition {
   inputProperties?: SkyDocsClassPropertyDefinition[];
 
   selector: string;
+
+  hasPreviewFeatures: boolean;
 }

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,
         },
       ],
     };

projects/docs-tools/src/modules/type-definitions/enumeration-definition.ts

@@ -7,4 +7,5 @@ import { SkyDocsEnumerationMemberDefinition } from './enumeration-member-definit
  */
 export interface SkyDocsEnumerationDefinition extends SkyDocsEntryDefinition {
   members: SkyDocsEnumerationMemberDefinition[];
+  hasPreviewFeatures: boolean;
 }

projects/docs-tools/src/modules/type-definitions/enumeration-member-definition.ts

@@ -10,5 +10,7 @@ export interface SkyDocsEnumerationMemberDefinition {
 
   description?: string;
 
+  isPreview: boolean;
+
   name: string;
 }