test(docs): unit test style doc generation (#5708)

add unit tests for `src/compiler/docs/generate-doc-data.ts#getDocsStyles`.
this was pulled out into a separate pull request from another effort,
where we wish to add the `mode` that a stylesheet is associated with by
a component's `@Component({})` decorator to the output of `docs-json`.
these tests aren't strictly needed for that effort, but establish a
baseline for tests taht will be added in the future.

the `getDocsStyles` function was exported in order to test it.

additional jsdoc and type annotations have been added to differentiate
fields that are compiler metadata, and those that are used in our
documentation intermediate representation.

split from: STENCIL-1269 - CSS Documentation Should Account for Modes

src/compiler/docs/generate-doc-data.ts

@@ -305,18 +305,26 @@ const getDocsEvents = (events: d.ComponentCompilerEvent[]): d.JsonDocsEvent[] =>
     }));
 };
 
-const getDocsStyles = (cmpMeta: d.ComponentCompilerMeta): d.JsonDocsStyle[] => {
+/**
+ * Transforms the {@link d.CompilerStyleDoc} metadata for a component into a {@link d.JsonDocsStyle}, providing sensible
+ * defaults where needed.
+ * @param cmpMeta the metadata for a single Stencil component, which contains the compiler style metadata
+ * @returns a new series containing a {@link d.JsonDocsStyle} entry for each {@link d.CompilerStyleDoc} entry.
+ */
+export const getDocsStyles = (cmpMeta: d.ComponentCompilerMeta): d.JsonDocsStyle[] => {
   if (!cmpMeta.styleDocs) {
     return [];
   }
 
-  return sortBy(cmpMeta.styleDocs, (o) => o.name.toLowerCase()).map((styleDoc) => {
-    return {
-      name: styleDoc.name,
-      annotation: styleDoc.annotation || '',
-      docs: styleDoc.docs || '',
-    };
-  });
+  return sortBy(cmpMeta.styleDocs, (compilerStyleDoc) => compilerStyleDoc.name.toLowerCase()).map(
+    (compilerStyleDoc) => {
+      return {
+        name: compilerStyleDoc.name,
+        annotation: compilerStyleDoc.annotation || '',
+        docs: compilerStyleDoc.docs || '',
+      };
+    },
+  );
 };
 
 const getDocsListeners = (listeners: d.ComponentCompilerListener[]): d.JsonDocsListener[] => {

src/compiler/docs/test/generate-doc-data.spec.ts

@@ -4,7 +4,7 @@ import { getComponentsFromModules } from '@utils';
 import type * as d from '../../../declarations';
 import { stubComponentCompilerMeta } from '../../types/tests/ComponentCompilerMeta.stub';
 import { AUTO_GENERATE_COMMENT } from '../constants';
-import { generateDocData } from '../generate-doc-data';
+import { generateDocData, getDocsStyles } from '../generate-doc-data';
 
 describe('generate-doc-data', () => {
   describe('getDocsComponents', () => {
@@ -197,4 +197,136 @@ auto-generated content
       });
     });
   });
+
+  describe('getDocsStyles', () => {
+    it('returns an empty array if no styleDocs exist on the compiler metadata', () => {
+      const compilerMeta = stubComponentCompilerMeta();
+      // @ts-ignore - the intent of this test is to verify allocation of a new array if for some reason this is missing
+      compilerMeta.styleDocs = null;
+
+      const actual = getDocsStyles(compilerMeta);
+
+      expect(actual).toEqual([]);
+    });
+
+    it('returns an empty array if empty styleDocs exist on the compiler metadata', () => {
+      const compilerMeta = stubComponentCompilerMeta({ styleDocs: [] });
+
+      const actual = getDocsStyles(compilerMeta);
+
+      expect(actual).toEqual([]);
+    });
+
+    it("returns a 'sorted' array of one CompilerStyleDoc", () => {
+      const compilerStyleDoc: d.CompilerStyleDoc = {
+        annotation: 'prop',
+        docs: 'these are the docs for this prop',
+        name: 'my-style-one',
+      };
+      const compilerMeta = stubComponentCompilerMeta({ styleDocs: [compilerStyleDoc] });
+
+      const actual = getDocsStyles(compilerMeta);
+
+      expect(actual).toEqual([compilerStyleDoc]);
+    });
+
+    it('returns a sorted array from multiple CompilerStyleDoc', () => {
+      const compilerStyleDocOne: d.CompilerStyleDoc = {
+        annotation: 'prop',
+        docs: 'these are the docs for my-style-a',
+        name: 'my-style-a',
+      };
+      const compilerStyleDocTwo: d.CompilerStyleDoc = {
+        annotation: 'prop',
+        docs: 'these are more docs for my-style-b',
+        name: 'my-style-b',
+      };
+      const compilerStyleDocThree: d.CompilerStyleDoc = {
+        annotation: 'prop',
+        docs: 'these are more docs for my-style-c',
+        name: 'my-style-c',
+      };
+      const compilerMeta = stubComponentCompilerMeta({
+        styleDocs: [compilerStyleDocOne, compilerStyleDocThree, compilerStyleDocTwo],
+      });
+
+      const actual = getDocsStyles(compilerMeta);
+
+      expect(actual).toEqual([compilerStyleDocOne, compilerStyleDocTwo, compilerStyleDocThree]);
+    });
+  });
+
+  it("returns CompilerStyleDoc with the same name in the order they're provided", () => {
+    const compilerStyleDocOne: d.CompilerStyleDoc = {
+      annotation: 'prop',
+      docs: 'these are the docs for my-style-a (first lowercase)',
+      name: 'my-style-a',
+    };
+    const compilerStyleDocTwo: d.CompilerStyleDoc = {
+      annotation: 'prop',
+      docs: 'these are more docs for my-style-A (only capital)',
+      name: 'my-style-A',
+    };
+    const compilerStyleDocThree: d.CompilerStyleDoc = {
+      annotation: 'prop',
+      docs: 'these are more docs for my-style-a (second lowercase)',
+      name: 'my-style-a',
+    };
+    const compilerMeta = stubComponentCompilerMeta({
+      styleDocs: [compilerStyleDocOne, compilerStyleDocThree, compilerStyleDocTwo],
+    });
+
+    const actual = getDocsStyles(compilerMeta);
+
+    expect(actual).toEqual([compilerStyleDocOne, compilerStyleDocThree, compilerStyleDocTwo]);
+  });
+
+  describe('default values', () => {
+    it.each(['', null, undefined])(
+      'defaults the annotation to an empty string if %s is provided',
+      (annotationValue) => {
+        const compilerStyleDoc: d.CompilerStyleDoc = {
+          annotation: 'prop',
+          docs: 'these are the docs for this prop',
+          name: 'my-style-one',
+        };
+        // @ts-ignore the intent of this test to verify the fallback of this field if it's falsy
+        compilerStyleDoc.annotation = annotationValue;
+
+        const compilerMeta = stubComponentCompilerMeta({ styleDocs: [compilerStyleDoc] });
+
+        const actual = getDocsStyles(compilerMeta);
+
+        expect(actual).toEqual([
+          {
+            annotation: '',
+            docs: 'these are the docs for this prop',
+            name: 'my-style-one',
+          },
+        ]);
+      },
+    );
+
+    it.each(['', null, undefined])('defaults the docs to an empty string if %s is provided', (docsValue) => {
+      const compilerStyleDoc: d.CompilerStyleDoc = {
+        annotation: 'prop',
+        docs: 'these are the docs for this prop',
+        name: 'my-style-one',
+      };
+      // @ts-ignore the intent of this test to verify the fallback of this field if it's falsy
+      compilerStyleDoc.docs = docsValue;
+
+      const compilerMeta = stubComponentCompilerMeta({ styleDocs: [compilerStyleDoc] });
+
+      const actual = getDocsStyles(compilerMeta);
+
+      expect(actual).toEqual([
+        {
+          annotation: 'prop',
+          docs: '',
+          name: 'my-style-one',
+        },
+      ]);
+    });
+  });
 });