feat(docs): provide docs-custom-elements output targets

Follows the draft outlined in webcomponents/custom-elements-manifest#8 Closes: ionic-team#2048
runarberg · Apr 11, 2020 · c22e08b · c22e08b
1 parent 5b9b89e
commit c22e08b
Show file tree

Hide file tree

Showing 6 changed files with 107 additions and 7 deletions.
diff --git a/src/compiler/config/outputs/validate-docs.ts b/src/compiler/config/outputs/validate-docs.ts
@@ -1,7 +1,7 @@
 import * as d from '../../../declarations';
 import { buildError } from '@utils';
 import { isAbsolute, join } from 'path';
-import { isOutputTargetDocsCustom, isOutputTargetDocsJson, isOutputTargetDocsReadme, isOutputTargetDocsVscode } from '../../output-targets/output-utils';
+import { isOutputTargetDocsCustom, isOutputTargetDocsCustomElements, isOutputTargetDocsJson, isOutputTargetDocsReadme, isOutputTargetDocsVscode } from '../../output-targets/output-utils';
 import { NOTE } from '../../docs/constants';
 
 export const validateDocs = (config: d.Config, diagnostics: d.Diagnostic[], userOutputs: d.OutputTarget[]) => {
@@ -43,6 +43,12 @@ export const validateDocs = (config: d.Config, diagnostics: d.Diagnostic[], user
     docsOutputs.push(validateCustomDocsOutputTarget(diagnostics, jsonDocsOutput));
   });
 
+  // custom-elements docs
+  const customElementsDocsOutputs = userOutputs.filter(isOutputTargetDocsCustomElements);
+  customElementsDocsOutputs.forEach(customElementsDocsOutput => {
+    docsOutputs.push(validateCustomElementsDocsOutputTarget(diagnostics, customElementsDocsOutput));
+  });
+
   // vscode docs
   const vscodeDocsOutputs = userOutputs.filter(isOutputTargetDocsVscode);
   vscodeDocsOutputs.forEach(vscodeDocsOutput => {
@@ -103,10 +109,18 @@ const validateCustomDocsOutputTarget = (diagnostics: d.Diagnostic[], outputTarge
   return outputTarget;
 };
 
+const validateCustomElementsDocsOutputTarget = (diagnostics: d.Diagnostic[], outputTarget: d.OutputTargetDocsCustomElements) => {
+  if (typeof outputTarget.file !== 'string') {
+    const err = buildError(diagnostics);
+    err.messageText = `docs-custom-elements outputTarget missing the "file" path`;
+  }
+  return outputTarget;
+};
+
 const validateVScodeDocsOutputTarget = (diagnostics: d.Diagnostic[], outputTarget: d.OutputTargetDocsVscode) => {
   if (typeof outputTarget.file !== 'string') {
     const err = buildError(diagnostics);
-    err.messageText = `docs-vscode outputTarget missing the "file" paht`;
+    err.messageText = `docs-vscode outputTarget missing the "file" path`;
   }
   return outputTarget;
 };
diff --git a/src/compiler/docs/custom-elements/index.ts b/src/compiler/docs/custom-elements/index.ts
@@ -0,0 +1,69 @@
+import * as d from '../../../declarations';
+import { isOutputTargetDocsCustomElements } from '../../output-targets/output-utils';
+
+export const generateCustomElementsDocs = async (compilerCtx: d.CompilerCtx, docsData: d.JsonDocs, outputTargets: d.OutputTarget[]) => {
+  const customElementsOutputTargets = outputTargets.filter(isOutputTargetDocsCustomElements);
+
+  if (customElementsOutputTargets.length === 0) {
+    return;
+  }
+
+  const jsonContent = JSON.stringify(customElementsJson(docsData), null, 2);
+
+  await Promise.all(
+    customElementsOutputTargets.map(outputTarget => compilerCtx.fs.writeFile(outputTarget.file, jsonContent)),
+  );
+};
+
+function customElementsJson(docsData: d.JsonDocs) {
+  // https://github.com/webcomponents/custom-elements-json/pull/8
+  return {
+    version: 1.2,
+    tags: docsData.components.map((component) => ({
+      name: component.tag,
+      path: `./${component.filePath}`,
+      description: component.docs,
+
+      attributes: component.props
+        .filter((prop) => prop.attr)
+        .map((prop) => ({
+          name: prop.attr,
+          type: prop.type,
+          description: prop.docs,
+          defaultValue: prop.default,
+          required: prop.required,
+        })),
+
+      properties: component.props.map((prop) => ({
+        name: prop.name,
+        type: prop.type,
+        description: prop.docs,
+        defaultValue: prop.default,
+        required: prop.required,
+      })),
+
+      events: component.events.map((event) => ({
+        name: event.event,
+        description: event.docs,
+      })),
+
+      methods: component.methods.map((method) => ({
+        name: method.name,
+        description: method.docs,
+        signature: method.signature,
+      })),
+
+      slots: component.slots.map((slot) => ({
+        name: slot.name,
+        description: slot.docs,
+      })),
+
+      cssCustomProperties: component.styles
+        .filter((style) => style.annotation === 'prop')
+        .map((style) => ({
+          name: style.name,
+          description: style.docs,
+        })),
+    })),
+  };
+}
diff --git a/src/compiler/output-targets/docs/output-docs.ts b/src/compiler/output-targets/docs/output-docs.ts
@@ -3,11 +3,13 @@ import { generateDocData } from '../../../compiler/docs/generate-doc-data';
 import {
   isOutputTargetCustom,
   isOutputTargetDocsCustom,
+  isOutputTargetDocsCustomElements,
   isOutputTargetDocsJson,
   isOutputTargetDocsReadme,
   isOutputTargetDocsVscode,
 } from '../../../compiler/output-targets/output-utils';
 import { generateCustomDocs } from '../../../compiler/docs/custom';
+import { generateCustomElementsDocs } from '../../../compiler/docs/custom-elements';
 import { generateReadmeDocs } from '../../../compiler/docs/readme';
 import { generateJsonDocs } from '../../../compiler/docs/json';
 import { generateVscodeDocs } from '../../../compiler/docs/vscode';
@@ -18,7 +20,7 @@ export async function outputDocs(config: d.Config, compilerCtx: d.CompilerCtx, b
     return;
   }
   const docsOutputTargets = config.outputTargets.filter(
-    o => isOutputTargetCustom(o) || isOutputTargetDocsReadme(o) || isOutputTargetDocsJson(o) || isOutputTargetDocsCustom(o) || isOutputTargetDocsVscode(o),
+    o => isOutputTargetCustom(o) || isOutputTargetDocsCustomElements(o) || isOutputTargetDocsReadme(o) || isOutputTargetDocsJson(o) || isOutputTargetDocsCustom(o) || isOutputTargetDocsVscode(o),
   );
 
   if (docsOutputTargets.length === 0) {
@@ -34,6 +36,7 @@ export async function outputDocs(config: d.Config, compilerCtx: d.CompilerCtx, b
     generateReadmeDocs(config, compilerCtx, docsData, docsOutputTargets),
     generateJsonDocs(config, compilerCtx, docsData, docsOutputTargets),
     generateVscodeDocs(compilerCtx, docsData, docsOutputTargets),
+    generateCustomElementsDocs(compilerCtx, docsData, docsOutputTargets),
     generateCustomDocs(config, docsData, docsOutputTargets),
     outputCustom(config, compilerCtx, buildCtx, docsData, docsOutputTargets),
   ]);

diff --git a/src/compiler/output-targets/output-docs.ts b/src/compiler/output-targets/output-docs.ts
@@ -1,18 +1,19 @@
 import * as d from '../../declarations';
 import { generateDocData } from '../docs/generate-doc-data';
 import { generateCustomDocs } from '../docs/custom';
+import { generateCustomElementsDocs } from '../docs/custom-elements';
 import { generateJsonDocs } from '../docs/json';
 import { generateReadmeDocs } from '../docs/readme';
 import { generateVscodeDocs } from '../docs/vscode';
-import { isOutputTargetCustom, isOutputTargetDocsCustom, isOutputTargetDocsJson, isOutputTargetDocsReadme, isOutputTargetDocsVscode } from './output-utils';
+import { isOutputTargetCustom, isOutputTargetDocsCustom, isOutputTargetDocsCustomElements, isOutputTargetDocsJson, isOutputTargetDocsReadme, isOutputTargetDocsVscode } from './output-utils';
 import { outputCustom } from './output-custom';
 
 export const outputDocs = async (config: d.Config, compilerCtx: d.CompilerCtx, buildCtx: d.BuildCtx) => {
   if (!config.buildDocs) {
     return;
   }
   const docsOutputTargets = config.outputTargets.filter(
-    o => isOutputTargetCustom(o) || isOutputTargetDocsReadme(o) || isOutputTargetDocsJson(o) || isOutputTargetDocsCustom(o) || isOutputTargetDocsVscode(o),
+    o => isOutputTargetCustom(o) || isOutputTargetDocsCustomElements(o) || isOutputTargetDocsReadme(o) || isOutputTargetDocsJson(o) || isOutputTargetDocsCustom(o) || isOutputTargetDocsVscode(o),
   );
 
   if (docsOutputTargets.length === 0) {
@@ -28,6 +29,7 @@ export const outputDocs = async (config: d.Config, compilerCtx: d.CompilerCtx, b
     generateReadmeDocs(config, compilerCtx, docsData, docsOutputTargets),
     generateJsonDocs(config, compilerCtx, docsData, docsOutputTargets),
     generateVscodeDocs(compilerCtx, docsData, docsOutputTargets),
+    generateCustomElementsDocs(compilerCtx, docsData, docsOutputTargets),
     generateCustomDocs(config, docsData, docsOutputTargets),
     outputCustom(config, compilerCtx, buildCtx, docsData, docsOutputTargets),
   ]);

diff --git a/src/compiler/output-targets/output-utils.ts b/src/compiler/output-targets/output-utils.ts
@@ -63,15 +63,17 @@ export const isOutputTargetHydrate = (o: d.OutputTarget): o is d.OutputTargetHyd
 
 export const isOutputTargetCustom = (o: d.OutputTarget): o is d.OutputTargetCustom => o.type === CUSTOM;
 
-export const isOutputTargetDocs = (o: d.OutputTarget): o is d.OutputTargetDocsJson | d.OutputTargetDocsReadme | d.OutputTargetDocsVscode | d.OutputTargetDocsCustom =>
-  o.type === DOCS || o.type === DOCS_README || o.type === DOCS_JSON || o.type === DOCS_CUSTOM || o.type === DOCS_VSCODE;
+export const isOutputTargetDocs = (o: d.OutputTarget): o is d.OutputTargetDocsJson | d.OutputTargetDocsReadme | d.OutputTargetDocsVscode | d.OutputTargetDocsCustomElements | d.OutputTargetDocsCustom =>
+  o.type === DOCS || o.type === DOCS_README || o.type === DOCS_JSON || o.type === DOCS_CUSTOM || o.type === DOCS_CUSTOM_ELEMENTS || o.type === DOCS_VSCODE;
 
 export const isOutputTargetDocsReadme = (o: d.OutputTarget): o is d.OutputTargetDocsReadme => o.type === DOCS_README || o.type === DOCS;
 
 export const isOutputTargetDocsJson = (o: d.OutputTarget): o is d.OutputTargetDocsJson => o.type === DOCS_JSON;
 
 export const isOutputTargetDocsCustom = (o: d.OutputTarget): o is d.OutputTargetDocsCustom => o.type === DOCS_CUSTOM;
 
+export const isOutputTargetDocsCustomElements = (o: d.OutputTarget): o is d.OutputTargetDocsCustomElements => o.type === DOCS_CUSTOM_ELEMENTS;
+
 export const isOutputTargetDocsVscode = (o: d.OutputTarget): o is d.OutputTargetDocsVscode => o.type === DOCS_VSCODE;
 
 export const isOutputTargetWww = (o: d.OutputTarget): o is d.OutputTargetWww => o.type === WWW;
@@ -112,6 +114,7 @@ export const DIST_SELF_CONTAINED = `dist-self-contained`;
 export const DIST_GLOBAL_STYLES = 'dist-global-styles';
 export const DOCS = `docs`;
 export const DOCS_CUSTOM = 'docs-custom';
+export const DOCS_CUSTOM_ELEMENTS = 'docs-custom-elements';
 export const DOCS_JSON = `docs-json`;
 export const DOCS_README = `docs-readme`;
 export const DOCS_VSCODE = `docs-vscode`;
@@ -134,6 +137,7 @@ export const VALID_TYPES = [
   DOCS_JSON,
   DOCS_README,
   DOCS_VSCODE,
+  DOCS_CUSTOM_ELEMENTS,
   DOCS_CUSTOM,
   STATS,
   WWW,
@@ -155,6 +159,7 @@ export const VALID_TYPES_NEXT = [
   DOCS_JSON,
   DOCS_README,
   DOCS_VSCODE,
+  DOCS_CUSTOM_ELEMENTS,
   DOCS_CUSTOM,
 
   // MISC

diff --git a/src/declarations/stencil-public-compiler.ts b/src/declarations/stencil-public-compiler.ts
@@ -1436,6 +1436,12 @@ export interface OutputTargetCustom extends OutputTargetBase {
   copy?: CopyTask[];
 }
 
+export interface OutputTargetDocsCustomElements extends OutputTargetBase {
+  type: 'docs-custom-elements';
+  file: string;
+  sourceCodeBaseUrl?: string;
+}
+
 export interface OutputTargetDocsVscode extends OutputTargetBase {
   type: 'docs-vscode';
   file: string;
@@ -1612,6 +1618,7 @@ export type OutputTarget =
   | OutputTargetDistSelfContained
   | OutputTargetDocsJson
   | OutputTargetDocsCustom
+  | OutputTargetDocsCustomElements
   | OutputTargetDocsReadme
   | OutputTargetDocsVscode
   | OutputTargetWww