sveld 0.26.2 → 0.28.0

package/README.md

@@ -1,7 +1,6 @@
 # sveld
 
 [![NPM][npm]][npm-url]
-![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` is a TypeScript definition generator for Svelte components. It analyzes props, events, slots, and other component features through static analysis. Types and signatures can be defined using [JSDoc notation](https://jsdoc.app/). The tool can also generate component documentation in Markdown and JSON formats.
@@ -50,7 +49,7 @@ type $Props = {
    */
   primary?: boolean;
 
-  [key: `data-${string}`]: any;
+  [key: `data-${string}`]: unknown;
 };
 
 export type ButtonProps = Omit<$RestProps, keyof $Props> & $Props;
@@ -120,6 +119,7 @@ export default class Button extends SvelteComponentTyped<
 - [API Reference](#api-reference)
   - [@type](#type)
   - [@typedef](#typedef)
+  - [@callback](#callback)
   - [@slot](#slot)
     - [Svelte 5 Snippet Compatibility](#svelte-5-snippet-compatibility)
   - [@event](#event)
@@ -222,13 +222,13 @@ npx sveld --json --markdown
 
 ### Node.js
 
-You can also use `sveld` programmatically in Node.js.
+You can also use `sveld` programmatically in Node.js. The package is **ESM-only**; `require("sveld")` is not supported. Use `import` or dynamic `import()`.
 
 If no `input` is specified, `sveld` will infer the entry point based on the `package.json#svelte` field.
 
 ```js
-const { sveld } = require("sveld");
-const pkg = require("./package.json");
+import { sveld } from "sveld";
+import pkg from "./package.json" with { type: "json" };
 
 sveld({
   input: "./src/index.js",
@@ -485,6 +485,69 @@ export type ComponentProps = {
 
 > **Note:** The inline syntax `@typedef {{ name: string }} User` continues to work for backwards compatibility.
 
+### `@callback`
+
+The `@callback` tag defines a function type using `@param` and `@returns` tags, following the [TypeScript JSDoc `@callback` specification](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#callback). Like `@typedef`, callbacks are exported from the generated TypeScript definition file.
+
+This is useful for typing callback props without using inline function type syntax.
+
+Signature:
+
+```js
+/**
+ * Optional description
+ * @callback CallbackName
+ * @param {Type} paramName - Parameter description
+ * @returns {ReturnType}
+ */
+```
+
+Example:
+
+```js
+/**
+ * Callback fired when the value changes
+ * @callback OnChange
+ * @param {string} value - The new value
+ * @param {number} index - The index of the changed item
+ * @returns {void}
+ */
+
+/** @type {OnChange} */
+export let onChange = (value, index) => {};
+```
+
+Output:
+
+```ts
+/**
+ * Callback fired when the value changes
+ */
+export type OnChange = (value: string, index: number) => void;
+
+export type ComponentProps = {
+  /**
+   * Callback fired when the value changes
+   */
+  onChange?: OnChange;
+};
+```
+
+Callbacks can be combined with `@typedef` in the same comment block:
+
+```js
+/**
+ * @typedef {"asc" | "desc"} SortDirection
+ * @callback SortFn
+ * @param {any} a
+ * @param {any} b
+ * @param {SortDirection} direction
+ * @returns {number}
+ */
+```
+
+When `@returns` is omitted, the return type defaults to `void`. When no `@param` tags are present, the callback is typed as a no-argument function.
+
 ### `@slot`
 
 Use the `@slot` tag for typing component slots. Note that `@slot` is a non-standard JSDoc tag.

package/cli.js

@@ -1,9 +1,3 @@
 #!/usr/bin/env node
 
-(() => {
-  try {
-    require("./lib").cli(process);
-  } catch (error) {
-    console.error(error);
-  }
-})();
+import("./lib/index.js").then(({ cli }) => cli(process)).catch(console.error);

package/lib/ComponentParser.d.ts

@@ -601,7 +601,7 @@ export default class ComponentParser {
      * Parses custom types, events, slots, and other JSDoc annotations from component comments.
      *
      * Scans the entire source for JSDoc comment blocks and extracts structured information
-     * about events, typedefs, slots, extends, restProps, and generics. Handles complex
+     * about events, typedefs, callbacks, slots, extends, restProps, and generics. Handles complex
      * description extraction logic that supports both inline descriptions and preceding
      * line descriptions.
      *