build: generate core API docs and metadata

Signed-off-by: Cory Rylan <[email protected]>

.gitignore

@@ -2,7 +2,8 @@
 
 # core related files
 *.element.css.ts
-src/dev-core/src/api
+src/dev-core/api
+
 
 # compiled output
 /dist

.prettierignore

@@ -9,5 +9,6 @@ src/website/src/releases/final-template/auto-generated-routes.ts
 src/website/src/sitemap.xml
 src/clr-core/utils/css-vars/css-vars-ponyfill-fork.ts
 src/clr-core/**/*.css.ts
-src/dev-core/src/api/
+src/clr-core/docs/
+src/dev-core/api/
 src/clr-angular/utils/_mixins.clarity.scss

angular.json

@@ -297,7 +297,7 @@
             "tsConfig": "src/dev-core/tsconfig.app.json",
             "aot": false,
             "assets": [
-              { "glob": "**/*", "input": "src/dev-core/src/api/", "output": "./api/" },
+              { "glob": "**/*", "input": "src/dev-core/api/", "output": "./api/" },
               "src/dev-core/src/favicon.ico",
               "src/dev-core/src/assets",
               "src/dev-core/src/manifest.json",

package.json

@@ -79,12 +79,12 @@
     "ui:lint": "stylelint --config ./src/clr-ui/.stylelintrc \"src/clr-ui/**/*.scss\"",
     "ui:lint:fix": "stylelint --config ./src/clr-ui/.stylelintrc --fix \"src/clr-ui/**/*.scss\"",
     "core:start": "npm run core:sass && npm run core:api && npm-run-all --parallel core:sass:watch core:dev:watch",
-    "core:dev:watch": "npm run core:sass && ng serve dev-core",
+    "core:dev:watch": "npm run core:sass && npm run core:api:json && ng serve dev-core",
     "core:dev:watch:prod": "npm run core:sass && ng serve dev-core --prod",
     "core:dev:build": "ng build dev-core --prod",
     "core:test": "npm run core:sass && ng test clr-core --watch=false && npm run core:golden:test",
     "core:test:watch": "ng test clr-core --watch --code-coverage",
-    "core:build": "npm-run-all core:lint core:sass core:build:ngpackagr core:sass:global core:build:package core:golden",
+    "core:build": "npm-run-all core:lint core:sass core:build:ngpackagr core:sass:global core:build:package core:api:editor core:api core:golden",
     "core:build:package": "cpy ./src/clr-ui/package.json ./src/clr-core/README.md ./dist/clr-core/; replace '@VERSION' $npm_package_version ./dist/clr-core/package.json",
     "core:build:ngpackagr": "ng build clr-core && node ./src/clr-core/modules.js",
     "core:golden": "ts-api-guardian --out dist/golden/clr-core.d.ts dist/clr-core/index.d.ts",
@@ -95,7 +95,11 @@
     "core:sass": "sass-render --q --suffix '.css.ts' -t ./src/clr-core/sass-template.js ./src/clr-core/**/*element.scss",
     "core:sass:watch": "sass-render --q --suffix '.css.ts' -t ./src/clr-core/sass-template.js ./src/clr-core/**/*element.scss -w",
     "core:sass:global": "sass --source-map --precision=8 ./src/clr-core/styles/global.scss ./dist/clr-core/clr-core-global.css && csso -i ./dist/clr-core/clr-core-global.css -o ./dist/clr-core/clr-core-global.min.css -s file",
-    "core:api": "del ./src/dev-core/src/api && typedoc --tsconfig ./src/clr-core/tsconfig.lib.json --options ./src/clr-core/tsconfig.lib.json"
+    "core:api": "npm-run-all --parallel core:api:md core:api:json",
+    "core:api:md": "wca analyze 'src/clr-core/**/*.{js,ts}' --format=md --outDir=src/clr-core/docs",
+    "core:api:json": "wca analyze 'src/clr-core/**/*.{js,ts}' --format=json --outDir=src/dev-core/api",
+    "core:api:editor": "wca analyze 'src/clr-core/**/*.{js,ts}' --format json --outFile dist/clr-core/custom-elements.json",
+    "core:api:tsdoc": "del ./src/dev-core/api && typedoc --tsconfig ./src/clr-core/tsconfig.lib.json --options ./src/clr-core/tsconfig.lib.json"
   },
   "dependencies": {
     "@angular/animations": "8.0.0",
@@ -209,6 +213,7 @@
     "uglifyjs": "2.4.11",
     "uglifyjs-webpack-plugin": "2.1.2",
     "wc-sass-render": "1.2.1",
+    "web-component-analyzer": "0.1.20",
     "webpack-cli": "3.3.1",
     "xml-js": "1.6.11"
   },

src/clr-core/docs/README.md

@@ -0,0 +1,5 @@
+# Core Web Component API
+
+You can find all the Core Web Component APIs documented within this directory.
+
+- [Demo Dropdown](cwc-test-dropdown.md)

src/clr-core/docs/cwc-test-dropdown.md

@@ -0,0 +1,36 @@
+# cwc-test-dropdown
+
+Dropdown, example test component. Do not use in production.
+
+## Attributes
+
+| Attribute | Type  | Description          |
+|-----------|-------|----------------------|
+| `outline` | `any` | Apply outline style. |
+
+## Properties
+
+| Property | Attribute | Type      | Default    | Description                            |
+|----------|-----------|-----------|------------|----------------------------------------|
+| `open`   | `open`    | `boolean` |            | Set open to open or close the dropdown |
+| `title`  | `title`   | `string`  | "dropdown" | Set the dropdown button text           |
+
+## Events
+
+| Event        | Description                          |
+|--------------|--------------------------------------|
+| `openChange` | notify open state change of dropdown |
+
+## Slots
+
+| Name      | Description                       |
+|-----------|-----------------------------------|
+| `default` | Content slot for dropdown content |
+
+## CSS Custom Properties
+
+| Property                             |
+|--------------------------------------|
+| `--clr-test-border-color`            |
+| `--clr-test-button-background-color` |
+| `--clr-test-button-text-color`       |

src/clr-core/modules.js

@@ -6,6 +6,7 @@ const path = require('path');
 // Temporary script needed for modern build toolchains that default and expect es2015 modules as the main entry point.
 // https://github.com/ng-packagr/ng-packagr/pull/1372
 // https://github.com/ng-packagr/ng-packagr/issues/1318
+// https://justinfagnani.com/2019/11/01/how-to-publish-web-components-to-npm/
 const read = dir =>
   fs
     .readdirSync(dir)
@@ -22,5 +23,7 @@ read('./dist/clr-core')
   .forEach(file => {
     const data = JSON.parse(fs.readFileSync(file));
     data.module = data.module.replace('fesm5', 'fesm2015');
+    data.main = data.module;
+    data.type = 'module';
     fs.writeFileSync(file, JSON.stringify(data, null, 2));
   });

src/clr-core/test-dropdown/test-dropdown.element.ts

@@ -14,12 +14,13 @@ import { styles } from './test-dropdown.element.css';
  * Dropdown, example test component. Do not use in production.
  *
  * @noInheritDoc
- * @element `cwc-test-dropdown`
- * @slot `default` - Content slot for dropdown content
- * @styleAttr `outline` - Apply outline style.
- * @cssProp `--clr-test-border-color`
- * @cssProp `--clr-test-button-background-color`
- * @cssProp  `--clr-test-button-text-color`
+ * @element cwc-test-dropdown
+ * @slot default - Content slot for dropdown content
+ * @attr outline - Apply outline style.
+ * @event openChange - notify open state change of dropdown
+ * @cssprop --clr-test-border-color
+ * @cssprop --clr-test-button-background-color
+ * @cssprop --clr-test-button-text-color
  */
 // @dynamic
 export class CwcTestDropdown extends LitElement {

src/dev-core/src/app/app.component.html

@@ -5,7 +5,6 @@
 <section>
   <nav>
     <a routerLink="/">Home</a>
-    <a href="/api/index.html">API</a>
     <a routerLink="/i18n">i18n</a>
     <a routerLink="/typography">Typography</a>
     <a routerLink="/lazy-load">Lazy Load</a>

src/dev-core/src/app/app.module.ts

@@ -3,16 +3,18 @@
  * This software is released under MIT license.
  * The full license information can be found in LICENSE in the root directory of this project.
  */
+import { HttpClientModule } from '@angular/common/http';
 import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
 import { BrowserModule } from '@angular/platform-browser';
 
 import { AppRoutingModule } from './app-routing.module';
 import { AppComponent } from './app.component';
 import { HomeDemoComponent } from './home/home.demo';
+import { SharedModule } from './shared/shared.module';
 
 @NgModule({
   declarations: [AppComponent, HomeDemoComponent],
-  imports: [BrowserModule, AppRoutingModule],
+  imports: [BrowserModule, SharedModule, HttpClientModule, AppRoutingModule],
   providers: [],
   bootstrap: [AppComponent],
   schemas: [CUSTOM_ELEMENTS_SCHEMA],

src/dev-core/src/app/dropdown/dropdown.demo.html

@@ -6,4 +6,6 @@ <h3>Open: {{open}}</h3>
 
 <cwc-test-dropdown [open]="open" (openChange)="open = $event.detail" title="click me!">
   Hello World
-</cwc-test-dropdown>
+</cwc-test-dropdown>
+
+<app-element-api element="cwc-test-dropdown"></app-element-api>