sveld 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -10,7 +10,11 @@ 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.10.2](https://github.com/carbon-design-system/sveld/releases/tag/v0.10.) - 2021-08-29
+## [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
 

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,6 +66,7 @@ export default class ComponentParser {
     private compiled?;
     private rest_props?;
     private extends?;
+    private componentComment?;
     private readonly reactive_vars;
     private readonly props;
     private readonly slots;

package/lib/ComponentParser.js

@@ -160,6 +160,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 +183,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;
                 if (node.type === "CallExpression") {
                     if (node.callee.name === "createEventDispatcher") {
                         dispatcher_name = parent === null || parent === void 0 ? void 0 : parent.id.name;
@@ -201,7 +202,7 @@ 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 _l = node.declaration.declarations ? node.declaration.declarations[0] : node.declaration, declaration_type = _l.type, id = _l.id, init = _l.init, body = _l.body;
                     var prop_name = id.name;
                     var value = undefined;
                     var type = undefined;
@@ -264,8 +265,14 @@ var ComponentParser = /** @class */ (function () {
                         reactive: _this.reactive_vars.has(prop_name)
                     });
                 }
+                if (node.type === "Comment") {
+                    var data = (_h = (_g = node === null || node === void 0 ? void 0 : node.data) === null || _g === void 0 ? void 0 : _g.trim()) !== null && _h !== void 0 ? _h : "";
+                    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 = (_j = node.attributes.find(function (attr) { return attr.name === "name"; })) === null || _j === void 0 ? void 0 : _j.value[0].data;
                     var slot_props = node.attributes
                         .filter(function (attr) { return attr.name !== "name"; })
                         .reduce(function (slot_props, _a) {
@@ -302,7 +309,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 = (_k = node.children) === null || _k === void 0 ? void 0 : _k.map(function (_a) {
                         var start = _a.start, end = _a.end;
                         return _this.sourceAtPos(start, end);
                     }).join("").trim();
@@ -387,7 +394,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/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.2",
+  "version": "0.11.0",
   "license": "Apache-2.0",
   "description": "Generate TypeScript definitions for your Svelte components.",
   "main": "./lib/index.js",