@progress/kendo-typescript-api-tasks 1.0.1-dev.1531

package/README.md

@@ -0,0 +1,11 @@
+# Kendo UI for Angular
+
+This package is part of the [Kendo UI for Angular](http://www.telerik.com/kendo-angular-ui/) suite.
+
+## License
+
+This is commercial software. To use it, you need to agree to the [**Telerik End User License Agreement for Kendo UI Complete**](http://www.telerik.com/purchase/license-agreement/kendo-ui-complete). If you do not own a commercial license, this file shall be governed by the trial license terms.
+
+All available Kendo UI commercial licenses may be obtained at http://www.telerik.com/purchase/kendo-ui.
+
+*Copyright © 2022 Progress Software Corporation and/or one of its subsidiaries or affiliates. All rights reserved.*

package/index.js

@@ -0,0 +1,70 @@
+const execSync = require('child_process').execSync;
+const fs = require('fs');
+const path = require('path');
+const { merge } = require('lodash');
+const typedoc = require('typedoc');
+const glob = require('glob');
+const generator = require('./lib/generator.js');
+const typeLinks = require('./type-links.json');
+
+const defaultConfig = {
+    outPath: 'docs/api',
+    warningsAsErrors: true,
+    jsonPath: path.resolve('./api.json'),
+    typeLinksPath: path.resolve('./api-type-links.json'),
+    typeLinks,
+    typedoc: {
+        excludeExternals: false
+    }
+};
+
+module.exports = (gulp, userConfig) => {
+    const series = gulp.series;
+
+    const config = merge({}, defaultConfig, userConfig);
+
+    if (fs.existsSync(config.typeLinksPath)) {
+        Object.assign(config.typeLinks, require(config.typeLinksPath));
+    }
+
+    gulp.task('api-json', async(done) => {
+        const entryPoints = [
+            ...glob.sync("src/**/*.{ts,tsx}"),
+            ...(config.externalApi || [])
+        ];
+
+        const app = new typedoc.Application();
+        app.options.addReader(new typedoc.TSConfigReader());
+        app.bootstrap({ ...config.typedoc, entryPoints });
+
+        const project = app.convert();
+        if (!project) {
+            done(new Error('Unable to initialize TypeDoc.'));
+            return;
+        }
+
+        await app.generateJson(project, config.jsonPath);
+        if (app.logger.hasErrors()) {
+            done(new Error('Unable to generate API reference, see messages above.'));
+            return;
+        }
+
+        done();
+    });
+
+    gulp.task('api-clean', (done) => {
+        execSync(`rm -rf docs/api`, { stdio: [ 0,1,2 ] });
+        done();
+    });
+
+    gulp.task('api', series('api-json', 'api-clean', (done) => {
+        const packageJson = path.join(process.cwd(), 'package.json');
+        const packageInfo = require(packageJson);
+        generator.generate(done, config, packageInfo);
+    }));
+
+    gulp.task('api-check', series('api', (done) => {
+        execSync(`git diff --exit-code --color -- ${config.outPath}`,{ stdio: [ 0,1,2 ] });
+        done();
+    }));
+};

package/jest.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    testMatch: [ '<rootDir>/test/**/*.js' ]
+};

package/lib/class-page.hbs

@@ -0,0 +1,27 @@
+{{> member_meta}}
+
+# {{name}}
+{{comment}}
+
+{{#if props}}
+
+<table class="api-table api-table-properties">
+<thead>
+<tr>
+<th class="th-name">Name</th>
+<th class="th-type">Type</th>
+<th class="th-default">Default</th>
+<th class="th-desc">Description</th>
+</tr>
+</thead>
+<tbody class="api-table-body">
+{{#each props}}
+{{> property this }}
+{{/each}}
+</tbody>
+</table>
+
+{{/if}}
+
+{{> constructor}}
+{{> methods}}

package/lib/class-page.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const template = require('./template-utils');
+const comment = require('./comment');
+const mapProps = require('./map-props');
+const mapConstructors = require('./map-constructors');
+const mapMethods = require('./map-methods');
+const fullName = require('./type-utils').fullName;
+
+const classTemplate = template.compileFrom('class-page.hbs');
+template.partialFrom('methods', 'methods.hbs');
+template.partialFrom('constructor', 'constructor.hbs');
+
+const classPage = (member, meta) => {
+    let props = null;
+    let methods = null;
+    let constructors = null;
+    if (member.children) {
+        constructors = mapConstructors(member);
+        methods = mapMethods(member.children, member.name);
+        props = mapProps(member.children, member.name);
+    }
+
+    return classTemplate(Object.assign({}, meta, {
+        comment: comment(member),
+        constructors: constructors,
+        props: props,
+        methods: methods,
+        name: fullName(member),
+        slug: member.slug
+    }));
+};
+
+module.exports = classPage;
+

package/lib/code-block.hbs

@@ -0,0 +1,7 @@
+<code>
+
+
+{{ this }}
+
+
+</code>

package/lib/comment-tags.hbs

@@ -0,0 +1,7 @@
+{{#if tags}}
+{{#each tags}}
+
+
+{{text}}
+{{/each}}
+{{/if}}

package/lib/comment.js

@@ -0,0 +1,56 @@
+"use strict";
+
+const template = require('./template-utils.js');
+const slug = require('./slug.js');
+const warn = require('./warn.js');
+
+const commentTemplate = template.compileFrom('comment-tags.hbs');
+
+const commentTags = (comment, member) =>
+    commentTemplate({
+        tags: comment.tags.map(tag => {
+            let text = tag.text.trim();
+
+            if (tag.tag === 'example') {
+                text = text.replace(/_@/g, '@');
+            } else if (tag.tag === 'see') {
+                const linkSlug = slug(member.packageName, text);
+                text = `\n\nSee [${text}]({% slug ${linkSlug} %})`;
+            } else {
+                text = '';
+            }
+
+            return {
+                text: text
+            };
+        })
+    });
+
+const formatComment = (member, parentName, memberKind) => {
+    let signatures;
+    if (member.type && member.type.declaration) {
+        signatures = member.type.declaration.signatures;
+    }
+
+    const comment = member.comment || signatures && signatures[0] && signatures[0].comment;
+
+    if (!comment) {
+        warn(member, parentName, memberKind);
+
+        return '';
+    }
+
+    let output = comment.shortText || "";
+    if (comment.text) {
+        output += '\n\n' + comment.text;
+    }
+
+    if (comment.tags) {
+        output += commentTags(comment, member);
+    }
+
+    return output;
+};
+
+module.exports = formatComment;
+

package/lib/component-page.hbs

@@ -0,0 +1,101 @@
+{{> member_meta}}
+
+# {{name}}
+{{comment}}
+
+## Selector
+`{{selector}}`
+{{#if exportAs}}
+
+## Export Name
+Accessible in templates as `#{{exportName}}="{{exportAs}}"`
+{{/if}}
+
+{{#if inputs}}
+
+## Inputs
+
+<table class="api-table api-table-inputs">
+<thead>
+<tr>
+<th class="th-name">Name</th>
+<th class="th-type">Type</th>
+<th class="th-default">Default</th>
+<th class="th-desc">Description</th>
+</tr>
+</thead>
+<tbody class="api-table-body">
+{{#each inputs}}
+{{> property this }}
+{{/each}}
+</tbody>
+</table>
+
+{{/if}}
+
+{{#if fields}}
+
+## Fields
+
+<table class="api-table api-table-fields">
+<thead>
+<tr>
+<th class="th-name">Name</th>
+<th class="th-type">Type</th>
+<th class="th-default">Default</th>
+<th class="th-desc">Description</th>
+</tr>
+</thead>
+<tbody class="api-table-body">
+{{#each fields}}
+{{> property this }}
+{{/each}}
+</tbody>
+</table>
+
+{{/if}}
+
+{{#if events}}
+
+## Events
+
+<table class="api-table api-table-events">
+<thead>
+<tr>
+<th class="th-name">Name</th>
+<th class="th-type">Type</th>
+<th class="th-desc">Description</th>
+</tr>
+</thead>
+<tbody class="api-table-body">
+{{#each events}}
+<tr>
+<td class="table-cell-name">
+
+
+#### {{name}}
+
+
+</td>
+<td type class="table-cell-type">
+
+
+{{> code_block type }}
+
+
+</td>
+<td class="table-cell-comment">
+
+
+{{comment}}
+
+
+</td>
+</tr>
+{{/each}}
+</tbody>
+</table>
+
+{{/if}}
+
+{{> methods}}

package/lib/component-page.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const utils = require('./utils.js');
+const isEvent = require('./is-event.js');
+const isInput = require('./is-input.js');
+const template = require('./template-utils.js');
+const comment = require('./comment.js');
+const mapProps = require('./map-props.js');
+const mapMethods = require('./map-methods.js');
+const isField = require('./is-field.js');
+
+const ignoreWithoutComment = utils.ignore(utils.hasProp('comment'));
+
+const componentTemplate = template.compileFrom('component-page.hbs');
+template.partialFrom('member_meta', 'member-meta.hbs');
+template.partialFrom('methods', 'methods.hbs');
+
+const findDecorator = (decorators) => ((decorators || []).find(d =>
+    d.name === 'Component' || d.name === 'Directive'
+));
+
+const decoratorProp = (prop) => (decorators) => {
+    const compDecorator = findDecorator(decorators);
+
+    if (compDecorator) {
+        const regExp = new RegExp(`${prop}:\\s?['"](.+?)['"]`);
+        const match = compDecorator.arguments.obj.match(regExp);
+
+        return match ? match[1] : undefined;
+    }
+
+    return undefined;
+};
+
+const selector = decoratorProp('selector');
+
+const exportAs = decoratorProp('exportAs');
+
+const exportName = (name) => `kendo${name.replace(/Component|Directive/, '')}Instance`;
+
+const componentPage = (component, meta) => {
+    let inputs;
+    let fields;
+    let events;
+    let methods;
+    if (component.children) {
+        fields = ignoreWithoutComment(mapProps(component.children.filter(isField), component.name));
+        inputs = mapProps(component.children.filter(isInput), component.name);
+        events = mapProps(component.children.filter(isEvent), component.name);
+        methods = mapMethods(component.children, component.name);
+    }
+
+    return componentTemplate(Object.assign({}, meta, {
+        name: component.name,
+        selector: selector(component.decorators),
+        exportAs: exportAs(component.decorators),
+        exportName: exportName(component.name),
+        comment: comment(component),
+        inputs: inputs,
+        fields: fields,
+        events: events,
+        methods: methods,
+        slug: component.slug
+    }));
+};
+
+module.exports = componentPage;

package/lib/constant-page.hbs

@@ -0,0 +1,4 @@
+{{> member_meta}}
+
+# {{name}}
+{{comment}}

package/lib/constant-page.js

@@ -0,0 +1,15 @@
+"use strict";
+
+const template = require('./template-utils.js');
+const comment = require('./comment.js');
+
+const constantTemplate = template.compileFrom('constant-page.hbs');
+const constantPage = (member, meta) =>
+    constantTemplate(Object.assign({}, meta, {
+        comment: comment(member),
+        name: member.name,
+        slug: member.slug
+    }));
+
+module.exports = constantPage;
+

package/lib/constructor.hbs

@@ -0,0 +1,21 @@
+{{#if constructors}}
+
+## Constructors
+
+{{#each constructors}}
+### {{name}}
+{{> code_block signature }}
+{{comment}}
+
+{{#if params}}
+#### Parameters
+{{#each params}}
+##### {{name}}
+{{> code_block type }}
+{{comment}}
+
+{{/each}}
+{{/if}}
+
+{{/each}}
+{{/if}}

package/lib/enum-page.hbs

@@ -0,0 +1,11 @@
+{{> member_meta}}
+
+# {{name}}
+{{comment}}
+
+## Values
+
+{{#each values}}
+### {{name}}
+{{comment}}
+{{/each}}

package/lib/enum-page.js

@@ -0,0 +1,25 @@
+"use strict";
+
+const template = require('./template-utils.js');
+const comment = require('./comment.js');
+
+function enumValues(member) {
+    return member.children.sort((a, b) => a.id - b.id).map(function(child) {
+        return {
+            comment: comment(child),
+            name: child.name
+        };
+    });
+}
+
+const enumTemplate = template.compileFrom('enum-page.hbs');
+const enumPage = (member, meta) =>
+    enumTemplate(Object.assign({}, meta, {
+        comment: comment(member),
+        name: member.name,
+        values: enumValues(member),
+        slug: member.slug
+    }));
+
+module.exports = enumPage;
+

package/lib/fn-page.hbs

@@ -0,0 +1,18 @@
+{{> member_meta}}
+
+# {{name}}
+{{comment}}
+
+{{#if params}}
+#### Parameters
+{{#each params}}
+##### {{name}}
+{{> code_block type }}
+{{comment}}
+
+{{/each}}
+{{/if}}
+{{#if returns}}
+#### Returns
+{{> code_block returns.type }}{{#if returns.comment}} {{returns.comment}}{{/if}}
+{{/if}}

package/lib/fn-page.js

@@ -0,0 +1,24 @@
+"use strict";
+
+const template = require('./template-utils.js');
+const comment = require('./comment.js');
+const returnType = require('./return-type');
+const types = require('./type-utils.js');
+
+const fnTemplate = template.compileFrom('fn-page.hbs');
+
+const fnPage = (member, meta) => {
+    const signature = member.signatures[0];
+    const commentRoot = member.comment ? member : signature;
+
+    return fnTemplate(Object.assign({}, meta, {
+        comment: comment(commentRoot),
+        name: types.fullName(signature),
+        params: types.params(signature),
+        returns: returnType(signature),
+        slug: member.slug
+    }));
+};
+
+module.exports = fnPage;
+