sveld 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -10,6 +10,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - add isAccessor field to API
 - update Markdown writer to generate a separate table for accessors
 
+## [0.12.0](https://github.com/carbon-design-system/sveld/releases/tag/v0.12.0) - 2022-01-02
+
+- support props defined via renamed exports (i.e.m `let className; export { className as class }`)
+
+## [0.11.1](https://github.com/carbon-design-system/sveld/releases/tag/v0.11.1) - 2021-12-31
+
+- replace backslashes with forward slashes in COMPONENT_API.json `filePath` values
+
+## [0.11.0](https://github.com/carbon-design-system/sveld/releases/tag/v0.11.0) - 2021-12-16
+
+- support writing `<!-- @component -->` comments in Svelte components to TypeScript definitions
+
+## [0.10.2](https://github.com/carbon-design-system/sveld/releases/tag/v0.10.2) - 2021-08-29
+
+- tolerate slot spread syntax (`<slot {...props} />`) when parsing Svelte components
+
 ## [0.10.1](https://github.com/carbon-design-system/sveld/releases/tag/v0.10.1) - 2021-08-28
 
 - include `.svelte` extension in `index.d.ts` exports

package/README.md

@@ -1,7 +1,8 @@
 # sveld
 
 [![NPM][npm]][npm-url]
-[![Build][build]][build-badge]
+![GitHub](https://img.shields.io/github/license/carbon-design-system/sveld?color=262626&style=for-the-badge)
+![npm downloads to date](https://img.shields.io/npm/dt/sveld?color=262626&style=for-the-badge)
 
 `sveld` generates TypeScript definitions for Svelte components by statically analyzing their props, events, slots and more. Prop types and signatures can be defined using [JSDoc notation](https://jsdoc.app/). This documentation generator can also emit component documentation in Markdown and JSON output formats.
 
@@ -13,7 +14,7 @@ The purpose of this project is to make third party Svelte component libraries co
 - [Component Index](https://github.com/IBM/carbon-components-svelte/blob/master/COMPONENT_INDEX.md): Markdown file documenting component props, slots, and events
 - [Component API](https://github.com/IBM/carbon-components-svelte/blob/master/docs/src/COMPONENT_API.json): Component API metadata in JSON format
 
-**Please note** that the generated TypeScript definitions require [Svelte version 3.31](https://github.com/sveltejs/svelte/blob/master/CHANGELOG.md#3300) or greater.
+**Please note** that the generated TypeScript definitions require [Svelte version 3.31](https://github.com/sveltejs/svelte/blob/master/CHANGELOG.md#3310) or greater.
 
 ---
 
@@ -399,13 +400,45 @@ Signature:
 Example:
 
 ```js
-/** @extends {"./Button"} ButtonProps */
+/** @extends {"./Button.svelte"} ButtonProps */
 
 export const secondary = true;
 
 import Button from "./Button.svelte";
 ```
 
+### `@component` comments
+
+The Svelte Language Server supports component-level comments through the following syntax: `<!-- @component [comment] -->`.
+
+`sveld` will copy these over to the exported default component in the TypeScript definition.
+
+Example:
+
+```svelte
+<!-- @component
+@example
+<Button>
+  Text
+</Button>
+-->
+<button>
+  <slot />
+</button>
+```
+
+Output:
+
+```ts
+/**
+ * @example
+ * <Button>
+ *   Text
+ * </Button>
+ */
+export default class Button extends SvelteComponentTyped<ButtonProps, {}, { default: {} }> {}
+```
+
 ## Contributing
 
 Refer to the [contributing guidelines](CONTRIBUTING.md).
@@ -416,5 +449,3 @@ Refer to the [contributing guidelines](CONTRIBUTING.md).
 
 [npm]: https://img.shields.io/npm/v/sveld.svg?color=262626&style=for-the-badge
 [npm-url]: https://npmjs.com/package/sveld
-[build]: https://img.shields.io/travis/com/ibm/sveld?color=24a148&style=for-the-badge
-[build-badge]: https://travis-ci.com/ibm/sveld

package/lib/ComponentParser.d.ts

@@ -58,6 +58,7 @@ export interface ParsedComponent {
     typedefs: TypeDef[];
     rest_props: RestProps;
     extends?: Extends;
+    componentComment?: string;
 }
 export default class ComponentParser {
     private options?;
@@ -65,7 +66,9 @@ export default class ComponentParser {
     private compiled?;
     private rest_props?;
     private extends?;
+    private componentComment?;
     private readonly reactive_vars;
+    private readonly vars;
     private readonly props;
     private readonly slots;
     private readonly events;

package/lib/ComponentParser.js

@@ -27,6 +27,7 @@ var DEFAULT_SLOT_NAME = "__default__";
 var ComponentParser = /** @class */ (function () {
     function ComponentParser(options) {
         this.reactive_vars = new Set();
+        this.vars = new Set();
         this.props = new Map();
         this.slots = new Map();
         this.events = new Map();
@@ -160,6 +161,7 @@ var ComponentParser = /** @class */ (function () {
         this.compiled = undefined;
         this.rest_props = undefined;
         this["extends"] = undefined;
+        this.componentComment = undefined;
         this.reactive_vars.clear();
         this.props.clear();
         this.slots.clear();
@@ -182,7 +184,7 @@ var ComponentParser = /** @class */ (function () {
         var callees = [];
         (0, compiler_1.walk)(this.compiled.ast, {
             enter: function (node, parent, prop) {
-                var _a, _b, _c, _d, _e, _f, _g, _h;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
                 if (node.type === "CallExpression") {
                     if (node.callee.name === "createEventDispatcher") {
                         dispatcher_name = parent === null || parent === void 0 ? void 0 : parent.id.name;
@@ -200,11 +202,28 @@ var ComponentParser = /** @class */ (function () {
                         };
                     }
                 }
-                if (node.type === "ExportNamedDeclaration" && node.declaration != null) {
-                    var _j = node.declaration.declarations
-                        ? node.declaration.declarations[0]
-                        : node.declaration, declaration_type = _j.type, id = _j.id, init = _j.init, body = _j.body;
-                    var prop_name = id.name;
+                if (node.type === "VariableDeclaration") {
+                    _this.vars.add(node);
+                }
+                if (node.type === "ExportNamedDeclaration") {
+                    // Handle renamed exports
+                    var prop_name = void 0;
+                    if (node.declaration == null && ((_a = node.specifiers[0]) === null || _a === void 0 ? void 0 : _a.type) === "ExportSpecifier") {
+                        var specifier = node.specifiers[0];
+                        var localName_1 = specifier.local.name, exportedName = specifier.exported.name;
+                        var declaration_1;
+                        // Search through all variable declarations for this variable
+                        //  Limitation: the variable must have been declared before the export
+                        _this.vars.forEach(function (varDecl) {
+                            if (varDecl.declarations.some(function (decl) { return decl.id.type === "Identifier" && decl.id.name === localName_1; })) {
+                                declaration_1 = varDecl;
+                            }
+                        });
+                        node.declaration = declaration_1;
+                        prop_name = exportedName;
+                    }
+                    var _m = node.declaration.declarations ? node.declaration.declarations[0] : node.declaration, declaration_type = _m.type, id = _m.id, init = _m.init, body = _m.body;
+                    prop_name !== null && prop_name !== void 0 ? prop_name : (prop_name = id.name);
                     var value = undefined;
                     var type = undefined;
                     var kind = node.declaration.kind;
@@ -216,7 +235,7 @@ var ComponentParser = /** @class */ (function () {
                             init.type === "BinaryExpression" ||
                             init.type === "ArrayExpression" ||
                             init.type === "ArrowFunctionExpression") {
-                            value = (_a = _this.sourceAtPos(init.start, init.end)) === null || _a === void 0 ? void 0 : _a.replace(/\n/g, " ");
+                            value = (_b = _this.sourceAtPos(init.start, init.end)) === null || _b === void 0 ? void 0 : _b.replace(/\n/g, " ");
                             type = value;
                             isFunction = init.type === "ArrowFunctionExpression";
                             if (init.type === "BinaryExpression") {
@@ -228,7 +247,7 @@ var ComponentParser = /** @class */ (function () {
                         else {
                             if (init.type === "UnaryExpression") {
                                 value = _this.sourceAtPos(init.start, init.end);
-                                type = typeof ((_b = init.argument) === null || _b === void 0 ? void 0 : _b.value);
+                                type = typeof ((_c = init.argument) === null || _c === void 0 ? void 0 : _c.value);
                             }
                             else {
                                 value = init.raw;
@@ -237,7 +256,7 @@ var ComponentParser = /** @class */ (function () {
                         }
                     }
                     if (declaration_type === "FunctionDeclaration") {
-                        value = "() => " + ((_c = _this.sourceAtPos(body.start, body.end)) === null || _c === void 0 ? void 0 : _c.replace(/\n/g, " "));
+                        value = "() => " + ((_d = _this.sourceAtPos(body.start, body.end)) === null || _d === void 0 ? void 0 : _d.replace(/\n/g, " "));
                         type = "() => any";
                         kind = "function";
                         isFunction = true;
@@ -246,10 +265,10 @@ var ComponentParser = /** @class */ (function () {
                     if (node.leadingComments) {
                         var last_comment = node.leadingComments[node.leadingComments.length - 1];
                         var comment = commentParser(ComponentParser.formatComment(last_comment.value));
-                        var tag = (_d = comment[0]) === null || _d === void 0 ? void 0 : _d.tags[((_e = comment[0]) === null || _e === void 0 ? void 0 : _e.tags.length) - 1];
+                        var tag = (_e = comment[0]) === null || _e === void 0 ? void 0 : _e.tags[((_f = comment[0]) === null || _f === void 0 ? void 0 : _f.tags.length) - 1];
                         if ((tag === null || tag === void 0 ? void 0 : tag.tag) === "type")
                             type = _this.aliasType(tag.type);
-                        description = ComponentParser.assignValue((_f = comment[0]) === null || _f === void 0 ? void 0 : _f.description);
+                        description = ComponentParser.assignValue((_g = comment[0]) === null || _g === void 0 ? void 0 : _g.description);
                     }
                     if (!description && _this.typedefs.has(type)) {
                         description = _this.typedefs.get(type).description;
@@ -266,8 +285,14 @@ var ComponentParser = /** @class */ (function () {
                         reactive: _this.reactive_vars.has(prop_name)
                     });
                 }
+                if (node.type === "Comment") {
+                    var data = (_j = (_h = node === null || node === void 0 ? void 0 : node.data) === null || _h === void 0 ? void 0 : _h.trim()) !== null && _j !== void 0 ? _j : "";
+                    if (/^@component/.test(data)) {
+                        _this.componentComment = data.replace(/^@component/, "");
+                    }
+                }
                 if (node.type === "Slot") {
-                    var slot_name = (_g = node.attributes.find(function (attr) { return attr.name === "name"; })) === null || _g === void 0 ? void 0 : _g.value[0].data;
+                    var slot_name = (_k = node.attributes.find(function (attr) { return attr.name === "name"; })) === null || _k === void 0 ? void 0 : _k.value[0].data;
                     var slot_props = node.attributes
                         .filter(function (attr) { return attr.name !== "name"; })
                         .reduce(function (slot_props, _a) {
@@ -277,6 +302,8 @@ var ComponentParser = /** @class */ (function () {
                             value: undefined,
                             replace: false
                         };
+                        if (value === undefined)
+                            return {};
                         if (value[0]) {
                             var _c = value[0], type = _c.type, expression = _c.expression, raw = _c.raw, start = _c.start, end = _c.end;
                             if (type === "Text") {
@@ -302,7 +329,7 @@ var ComponentParser = /** @class */ (function () {
                         }
                         return __assign(__assign({}, slot_props), (_b = {}, _b[name] = slot_prop_value, _b));
                     }, {});
-                    var fallback = (_h = node.children) === null || _h === void 0 ? void 0 : _h.map(function (_a) {
+                    var fallback = (_l = node.children) === null || _l === void 0 ? void 0 : _l.map(function (_a) {
                         var start = _a.start, end = _a.end;
                         return _this.sourceAtPos(start, end);
                     }).join("").trim();
@@ -387,7 +414,8 @@ var ComponentParser = /** @class */ (function () {
             events: ComponentParser.mapToArray(this.events),
             typedefs: ComponentParser.mapToArray(this.typedefs),
             rest_props: this.rest_props,
-            "extends": this["extends"]
+            "extends": this["extends"],
+            componentComment: this.componentComment
         };
     };
     return ComponentParser;

package/lib/path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Normalize directory separators to always use `/`.
+ * @param filePath A file path.
+ * @returns Path with normalized separators.
+ */
+export declare function normalizeSeparators(filePath: string): string;

package/lib/path.js

@@ -0,0 +1,13 @@
+"use strict";
+exports.__esModule = true;
+exports.normalizeSeparators = void 0;
+var path_1 = require("path");
+/**
+ * Normalize directory separators to always use `/`.
+ * @param filePath A file path.
+ * @returns Path with normalized separators.
+ */
+function normalizeSeparators(filePath) {
+    return path_1.sep === "/" ? filePath : filePath.split(path_1.sep).join("/");
+}
+exports.normalizeSeparators = normalizeSeparators;

package/lib/rollup-plugin.js

@@ -59,6 +59,7 @@ var get_svelte_entry_1 = require("./get-svelte-entry");
 var parse_exports_1 = require("./parse-exports");
 var compiler_1 = require("svelte/compiler");
 var svelte_preprocess_1 = require("svelte-preprocess");
+var path_1 = require("./path");
 function pluginSveld(opts) {
     var result;
     var input;
@@ -101,10 +102,7 @@ function generateBundle(input, glob) {
                     if (glob) {
                         fg.sync([dir + "/**/*.svelte"]).forEach(function (file) {
                             var moduleName = path.parse(file).name.replace(/\-/g, "");
-                            var source = "./" + path.relative(dir, file);
-                            if (path.sep !== "/") {
-                                source = source.split(path.sep).join("/");
-                            }
+                            var source = (0, path_1.normalizeSeparators)("./" + path.relative(dir, file));
                             if (exports[moduleName]) {
                                 exports[moduleName].source = source;
                             }

package/lib/writer/writer-json.js

@@ -48,6 +48,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 exports.__esModule = true;
 var path = require("path");
+var path_1 = require("../path");
 var Writer_1 = require("./Writer");
 function writeJson(components, options) {
     return __awaiter(this, void 0, void 0, function () {
@@ -59,7 +60,7 @@ function writeJson(components, options) {
                         total: components.size,
                         components: Array.from(components, function (_a) {
                             var moduleName = _a[0], component = _a[1];
-                            return (__assign(__assign({}, component), { filePath: path.join(options.inputDir, path.normalize(component.filePath)) }));
+                            return (__assign(__assign({}, component), { filePath: (0, path_1.normalizeSeparators)(path.join(options.inputDir, path.normalize(component.filePath))) }));
                         }).sort(function (a, b) {
                             if (a.moduleName < b.moduleName)
                                 return -1;

package/lib/writer/writer-ts-definitions.js

@@ -148,15 +148,25 @@ function genImports(def) {
         return "";
     return "import { " + def["extends"].interface + " } from " + def["extends"]["import"] + ";";
 }
+function genComponentComment(def) {
+    if (!def.componentComment)
+        return "";
+    if (!/\n/.test(def.componentComment))
+        return "/** " + def.componentComment.trim() + " */";
+    return "/*" + def.componentComment
+        .split("\n")
+        .map(function (line) { return "* " + line; })
+        .join("\n") + "\n*/";
+}
 function writeTsDefinition(component) {
-    var moduleName = component.moduleName, typedefs = component.typedefs, props = component.props, slots = component.slots, events = component.events, rest_props = component.rest_props, _extends = component["extends"];
+    var moduleName = component.moduleName, typedefs = component.typedefs, props = component.props, slots = component.slots, events = component.events, rest_props = component.rest_props, _extends = component["extends"], componentComment = component.componentComment;
     var _a = genPropDef({
         moduleName: moduleName,
         props: props,
         rest_props: rest_props,
         "extends": _extends
     }), props_name = _a.props_name, prop_def = _a.prop_def;
-    return "\n  /// <reference types=\"svelte\" />\n  import { SvelteComponentTyped } from \"svelte\";\n  " + genImports({ "extends": _extends }) + "\n  " + getTypeDefs({ typedefs: typedefs }) + "\n  " + prop_def + "\n\n  export default class " + (moduleName === "default" ? "" : moduleName) + " extends SvelteComponentTyped<\n      " + props_name + ",\n      {" + genEventDef({ events: events }) + "},\n      {" + genSlotDef({ slots: slots }) + "}\n    > {\n      " + genAccessors({ props: props }) + "\n    }";
+    return "\n  /// <reference types=\"svelte\" />\n  import { SvelteComponentTyped } from \"svelte\";\n  " + genImports({ "extends": _extends }) + "\n  " + getTypeDefs({ typedefs: typedefs }) + "\n  " + prop_def + "\n  " + genComponentComment({ componentComment: componentComment }) + "\n  export default class " + (moduleName === "default" ? "" : moduleName) + " extends SvelteComponentTyped<\n      " + props_name + ",\n      {" + genEventDef({ events: events }) + "},\n      {" + genSlotDef({ slots: slots }) + "}\n    > {\n      " + genAccessors({ props: props }) + "\n    }";
 }
 exports.writeTsDefinition = writeTsDefinition;
 function writeTsDefinitions(components, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sveld",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "license": "Apache-2.0",
   "description": "Generate TypeScript definitions for your Svelte components.",
   "main": "./lib/index.js",
@@ -11,7 +11,7 @@
     "test": "run-p test:*",
     "test:unit": "tsnd node_modules/tape/bin/tape tests/*.test.ts",
     "test:integration": "node tests/integration",
-    "format": "prettier --write '{src,tests}/**/*.ts'",
+    "format": "prettier --write \"{src,tests}/**/*.{ts,svelte}\"",
     "prepack": "run-s build test"
   },
   "peerDependencies": {
@@ -36,6 +36,7 @@
     "@types/prettier": "^2.3.2",
     "@types/tape": "^4.13.2",
     "npm-run-all": "^4.1.5",
+    "prettier-plugin-svelte": "^2.4.0",
     "tape": "^5.3.1",
     "ts-node-dev": "^1.1.1"
   },