sveld 0.23.1 → 0.23.2

package/README.md

@@ -413,6 +413,55 @@ export type ComponentProps = {
 };
 ```
 
+#### Optional properties and default values
+
+Following JSDoc standards, use square brackets to mark properties as optional. You can also specify default values using the `[propertyName=defaultValue]` syntax.
+
+Signature:
+
+```js
+/**
+ * @typedef {object} TypeName
+ * @property {Type} [optionalProperty] - Optional property description
+ * @property {Type} [propertyWithDefault=defaultValue] - Property with default value
+ */
+```
+
+Example:
+
+```js
+/**
+ * Configuration options for the component
+ * @typedef {object} ComponentConfig
+ * @property {boolean} enabled - Whether the component is enabled
+ * @property {string} theme - The component theme
+ * @property {number} [timeout=5000] - Optional timeout in milliseconds
+ * @property {boolean} [debug] - Optional debug mode flag
+ */
+
+/** @type {ComponentConfig} */
+export let config = { enabled: true, theme: "dark" };
+```
+
+Output:
+
+```ts
+export type ComponentConfig = {
+  /** Whether the component is enabled */ enabled: boolean;
+  /** The component theme */ theme: string;
+  /** Optional timeout in milliseconds @default 5000 */ timeout?: number;
+  /** Optional debug mode flag */ debug?: boolean;
+};
+
+export type ComponentProps = {
+  /**
+   * Configuration options for the component
+   * @default { enabled: true, theme: "dark" }
+   */
+  config?: ComponentConfig;
+};
+```
+
 > **Note:** The inline syntax `@typedef {{ name: string }} User` continues to work for backwards compatibility.
 
 ### `@slot`
@@ -562,6 +611,54 @@ export default class Component extends SvelteComponentTyped<
 > {}
 ```
 
+#### Optional properties in event details
+
+Just like with typedefs, you can mark event detail properties as optional using square brackets. This is useful when some properties may not always be included in the event payload.
+
+Example:
+
+```js
+/**
+ * Snowball event fired when throwing a snowball
+ *
+ * @event snowball
+ * @type {object}
+ * @property {boolean} isPacked - Indicates whether the snowball is tightly packed
+ * @property {number} speed - The speed of the snowball in mph
+ * @property {string} [color] - Optional color of the snowball
+ * @property {number} [density=0.9] - Optional density with default value
+ */
+
+import { createEventDispatcher } from "svelte";
+
+const dispatch = createEventDispatcher();
+
+function throwSnowball() {
+  dispatch("snowball", {
+    isPacked: true,
+    speed: 50
+  });
+}
+```
+
+Output:
+
+```ts
+export default class Component extends SvelteComponentTyped<
+  ComponentProps,
+  {
+    /** Snowball event fired when throwing a snowball */
+    snowball: CustomEvent<{
+      /** Indicates whether the snowball is tightly packed */ isPacked: boolean;
+      /** The speed of the snowball in mph */ speed: number;
+      /** Optional color of the snowball */ color?: string;
+      /** Optional density with default value @default 0.9 */ density?: number;
+    }>;
+  },
+  Record<string, never>
+> {}
+```
+
 ### Context API
 
 `sveld` automatically generates TypeScript definitions for Svelte's `setContext`/`getContext` API by extracting types from JSDoc annotations on the context values.

package/lib/ComponentParser.js

@@ -247,7 +247,7 @@ class ComponentParser {
                     currentTypedefDescription = undefined;
                 }
             };
-            tags.forEach(({ tag, type: tagType, name, description }) => {
+            tags.forEach(({ tag, type: tagType, name, description, optional, default: defaultValue }) => {
                 const type = this.aliasType(tagType);
                 switch (tag) {
                     case "extends":
@@ -284,23 +284,23 @@ class ComponentParser {
                             currentEventType = type;
                         }
                         break;
-                    case "property":
+                    case "property": {
                         // Collect properties for the current event or typedef
+                        const propertyData = {
+                            name,
+                            type,
+                            description: description?.replace(/^-\s*/, "").trim(),
+                            optional: optional || false,
+                            default: defaultValue,
+                        };
                         if (currentEventName !== undefined) {
-                            eventProperties.push({
-                                name,
-                                type,
-                                description: description?.replace(/^-\s*/, "").trim(),
-                            });
+                            eventProperties.push(propertyData);
                         }
                         else if (currentTypedefName !== undefined) {
-                            typedefProperties.push({
-                                name,
-                                type,
-                                description: description?.replace(/^-\s*/, "").trim(),
-                            });
+                            typedefProperties.push(propertyData);
                         }
                         break;
+                    }
                     case "typedef": {
                         // Finalize any previous typedef being built
                         finalizeTypedef();
@@ -328,11 +328,20 @@ class ComponentParser {
             return "null";
         // Build inline object type with property descriptions as JSDoc comments
         const props = properties
-            .map(({ name, type, description }) => {
-            if (description) {
-                return `/** ${description} */ ${name}: ${type};`;
+            .map(({ name, type, description, optional, default: defaultValue }) => {
+            const optionalMarker = optional ? "?" : "";
+            let comment = description || "";
+            // Add default value to description if present
+            if (defaultValue && comment) {
+                comment = `${comment} @default ${defaultValue}`;
+            }
+            else if (defaultValue) {
+                comment = `@default ${defaultValue}`;
+            }
+            if (comment) {
+                return `/** ${comment} */ ${name}${optionalMarker}: ${type};`;
             }
-            return `${name}: ${type};`;
+            return `${name}${optionalMarker}: ${type};`;
         })
             .join(" ");
         return `{ ${props} }`;

package/package.json

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