sveld 0.24.9 → 0.25.1

package/lib/ComponentParser.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const comment_parser_1 = require("comment-parser");
 const compiler_1 = require("svelte/compiler");
 const element_tag_map_1 = require("./element-tag-map");
+const COMMENT_BLOCK_DESCRIPTION_REGEX = /^-\s*/;
 const VAR_DECLARATION_REGEX = /(?:const|let|function)\s+(\w+)\s*[=(]/;
 const DEFAULT_SLOT_NAME = null;
 const TYPEDEF_END_REGEX = /(\}|\};)$/;
@@ -185,7 +186,9 @@ class ComponentParser {
         }
     }
     parseCustomTypes() {
-        for (const { tags, description: commentDescription } of (0, comment_parser_1.parse)(this.source, { spacing: "preserve" })) {
+        for (const { tags, description: commentDescription, source: blockSource } of (0, comment_parser_1.parse)(this.source, {
+            spacing: "preserve",
+        })) {
             let currentEventName;
             let currentEventType;
             let currentEventDescription;
@@ -194,6 +197,64 @@ class ComponentParser {
             let currentTypedefType;
             let currentTypedefDescription;
             const typedefProperties = [];
+            // Track if we've used the comment block description for any tag in this block
+            // Only the first tag (that needs a description) should use the comment block description
+            let commentDescriptionUsed = false;
+            let isFirstTag = true;
+            // Build a map of line numbers to their description content (for lines without tags)
+            const lineDescriptions = new Map();
+            // Track line numbers that contain tags
+            const tagLineNumbers = new Set();
+            for (const tagInfo of tags) {
+                if (tagInfo.source && tagInfo.source.length > 0) {
+                    tagLineNumbers.add(tagInfo.source[0].number);
+                }
+            }
+            for (const line of blockSource) {
+                // Only track lines that have a description but no tag
+                // Also filter out lines that are just "}" (artifact from some comment formats)
+                if (!line.tokens.tag && line.tokens.description && line.tokens.description.trim() !== "}") {
+                    lineDescriptions.set(line.number, line.tokens.description);
+                }
+            }
+            // Helper to get the description from lines preceding a tag
+            // Look backwards from the tag until we hit another tag, collecting description lines
+            // Stop after finding the first contiguous block of description lines
+            const getPrecedingDescription = (tagSource) => {
+                if (!tagSource || tagSource.length === 0)
+                    return undefined;
+                const tagLineNumber = tagSource[0].number;
+                // Look backwards from the tag line to find the immediately preceding description
+                const descLines = [];
+                let foundDescriptionBlock = false;
+                for (let lineNum = tagLineNumber - 1; lineNum >= 1; lineNum--) {
+                    // Stop if we hit a tag line
+                    if (tagLineNumbers.has(lineNum)) {
+                        break;
+                    }
+                    // Check if this line has a description
+                    const desc = lineDescriptions.get(lineNum);
+                    if (desc) {
+                        descLines.unshift(desc); // Add to beginning to maintain order
+                        foundDescriptionBlock = true;
+                    }
+                    else if (foundDescriptionBlock) {
+                        // We've already found description lines and now hit a non-description line
+                        // Check if it's blank - if so, continue; if not, stop
+                        const sourceLine = blockSource.find((l) => l.number === lineNum);
+                        const isBlank = !sourceLine ||
+                            (!sourceLine.tokens.tag &&
+                                (!sourceLine.tokens.description || sourceLine.tokens.description.trim() === ""));
+                        if (!isBlank) {
+                            // Non-blank non-description line - stop here
+                            break;
+                        }
+                        // Blank line - continue (blank lines can separate descriptions from tags)
+                    }
+                    // If we haven't found any description yet, continue looking backwards
+                }
+                return descLines.length > 0 ? descLines.join("\n").trim() : undefined;
+            };
             const finalizeEvent = () => {
                 if (currentEventName !== undefined) {
                     let detailType;
@@ -249,37 +310,63 @@ class ComponentParser {
                     currentTypedefDescription = undefined;
                 }
             };
-            for (const { tag, type: tagType, name, description, optional, default: defaultValue } of tags) {
+            for (const { tag, type: tagType, name, description, optional, default: defaultValue, source: tagSource, } of tags) {
                 const type = this.aliasType(tagType);
+                // Get the description from the line immediately before this tag
+                const precedingDescription = getPrecedingDescription(tagSource);
                 switch (tag) {
                     case "extends":
                         this.extends = {
                             interface: name,
                             import: type,
                         };
+                        if (isFirstTag)
+                            isFirstTag = false;
                         break;
                     case "restProps":
                         this.rest_props = {
                             type: "Element",
                             name: type,
                         };
+                        if (isFirstTag)
+                            isFirstTag = false;
                         break;
-                    case "slot":
+                    case "slot": {
+                        // Prefer inline description, fall back to preceding line description,
+                        // then fall back to the comment block description (only for first tag if not already used)
+                        const inlineSlotDesc = description?.replace(COMMENT_BLOCK_DESCRIPTION_REGEX, "").trim();
+                        let slotDesc = inlineSlotDesc || precedingDescription;
+                        if (!slotDesc && isFirstTag && !commentDescriptionUsed && commentDescription) {
+                            slotDesc = commentDescription;
+                            commentDescriptionUsed = true;
+                        }
+                        if (isFirstTag)
+                            isFirstTag = false;
                         this.addSlot({
                             slot_name: name,
                             slot_props: type,
-                            slot_description: description ? description : undefined,
+                            slot_description: slotDesc || undefined,
                         });
                         break;
-                    case "event":
+                    }
+                    case "event": {
                         // Finalize any previous event being built
                         finalizeEvent();
                         // Start tracking new event
                         currentEventName = name;
                         currentEventType = type;
-                        // Use the main comment description if available, otherwise use inline description
-                        currentEventDescription = commentDescription?.trim() || description || undefined;
+                        // Prefer inline description (e.g., "@event {type} name - description"),
+                        // fall back to preceding line, then fall back to comment block description (only for first tag if not already used)
+                        const inlineEventDesc = description?.replace(COMMENT_BLOCK_DESCRIPTION_REGEX, "").trim();
+                        currentEventDescription = inlineEventDesc || precedingDescription;
+                        if (!currentEventDescription && isFirstTag && !commentDescriptionUsed && commentDescription) {
+                            currentEventDescription = commentDescription;
+                            commentDescriptionUsed = true;
+                        }
+                        if (isFirstTag)
+                            isFirstTag = false;
                         break;
+                    }
                     case "type":
                         // Track the @type tag for the current event
                         if (currentEventName !== undefined) {
@@ -309,14 +396,22 @@ class ComponentParser {
                         // Start tracking new typedef
                         currentTypedefName = name;
                         currentTypedefType = type;
-                        // Use inline description if present, otherwise use comment description
-                        const trimmedCommentDesc = commentDescription?.trim();
-                        currentTypedefDescription =
-                            description || (trimmedCommentDesc && trimmedCommentDesc !== "}" ? trimmedCommentDesc : undefined);
+                        // Prefer inline description, fall back to preceding line description,
+                        // then fall back to comment block description (only for first tag if not already used)
+                        const inlineTypedefDesc = description?.replace(COMMENT_BLOCK_DESCRIPTION_REGEX, "").trim();
+                        currentTypedefDescription = inlineTypedefDesc || precedingDescription;
+                        if (!currentTypedefDescription && isFirstTag && !commentDescriptionUsed && commentDescription) {
+                            currentTypedefDescription = commentDescription;
+                            commentDescriptionUsed = true;
+                        }
+                        if (isFirstTag)
+                            isFirstTag = false;
                         break;
                     }
                     case "generics":
                         this.generics = [name, type];
+                        if (isFirstTag)
+                            isFirstTag = false;
                         break;
                 }
             }

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

@@ -26,7 +26,14 @@ function formatTsProps(props) {
 function getTypeDefs(def) {
     if (def.typedefs.length === 0)
         return EMPTY_STR;
-    return def.typedefs.map((typedef) => `export ${typedef.ts}`).join("\n\n");
+    return def.typedefs
+        .map((typedef) => {
+        const typedefComment = typedef.description
+            ? `/**\n * ${typedef.description.replace(NEWLINE_TO_COMMENT_REGEX, "\n * ")}\n */\n`
+            : "";
+        return `${typedefComment}export ${typedef.ts}`;
+    })
+        .join("\n\n");
 }
 function getContextDefs(def) {
     if (!def.contexts || def.contexts.length === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sveld",
-  "version": "0.24.9",
+  "version": "0.25.1",
   "license": "Apache-2.0",
   "description": "Generate TypeScript definitions for your Svelte components.",
   "main": "./lib/index.js",