sveld 0.37.4 → 0.37.6

package/README.md

@@ -429,11 +429,13 @@ Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongsid
 | `sveld/context-any-type` | `warning` | Annotate the `setContext` value's declaration with `@type` or a native TypeScript type. |
 | `sveld/slot-missing-type` | `warning` | Add the required `{Type}` annotation to the `@slot`/`@snippet` tag (e.g. `@slot {{}} name`); until then it falls back to `Record<string, never>`. |
 | `sveld/event-no-source` | `warning` | Dispatch the event (`createEventDispatcher`/`dispatch`), forward it (`on:name`), or add a matching `on<Name>` callback prop; otherwise remove the stale `@event` tag. |
+| `sveld/dispatch-escapes` | `warning` | The `createEventDispatcher()` result is passed to a function sveld can't follow: one that isn't imported from a local module, names an event with something other than a string literal, or passes the dispatcher on. Document the events it dispatches with `@event` tags. Add `@sveld-ignore sveld/dispatch-escapes` to the dispatcher's JSDoc once they're covered. |
 | `sveld/example-compile-error` | `error` | Fix the `@example` TS/JS code block so it type-checks, or remove the broken example. |
 | `sveld/example-syntax-error` | `error` | Fix the `@example` `svelte`/`html` markup so it parses, or remove the broken example. |
 | `sveld/syntax-skipped` | `error` | Rewrite the flagged syntax in a form sveld can model (see the diagnostic's `message` for what was skipped). |
 | `sveld/rest-props-unresolved` | `warning` | Spread `$$restProps` onto a plain element (or `svelte:element`) instead of a component, or add an `@restProps` tag to type it manually. |
 | `sveld/context-duplicate-key` | `warning` | Remove the duplicate `setContext` call, or give it a distinct key; only the first call's shape is used. |
+| `sveld/context-key-unresolved` | `warning` | Use a string literal, a `const`-bound string, `Symbol()`, or a string `export const` imported from a relative module as the `setContext` key; otherwise the context is left out of every output. |
 | `sveld/spread-unresolved` | `warning` | Spread a local object literal or a variable with a resolvable type instead; otherwise the spread widens the generated type to `Record<string, any>`. |
 | `sveld/export-unresolved` | `warning` | Export a local declaration directly. Instance-script exports are props, so move a re-export (`export { x } from "..."`, or `export { x }` of an import) into `<script context="module">`, where sveld writes it to the `.d.ts` as-is. |
 | `sveld/module-export-conflict` | `warning` | Rename the module-script export. `default` is always skipped (it collides with the component itself); a name matching the generated `<Name>Props`/`<Name>Exports` type breaks the `.d.ts` if the export carries a type. |
@@ -451,7 +453,7 @@ Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongsid
 
 #### Severity and `--strict=errors`
 
-Each diagnostic's `severity` is `"error"` (`example-compile-error`, `example-syntax-error`, `syntax-skipped`, `extend-props-target-missing`, `internal-typedef-referenced` — sveld emitted broken or unmodeled output) or `"warning"` (`prop-unknown-type`, `context-any-type`, `slot-missing-type`, `event-no-source`, `rest-props-unresolved`, `context-duplicate-key`, `spread-unresolved`, `export-unresolved`, `module-export-conflict`, `extend-props-duplicate`, `extend-props-override`, `jsdoc-unknown-tag`, `typedef-duplicate`, `property-duplicate`, `generics-conflict`, `event-description-ambiguous`, `jsdoc-tag-dropped`, `types-inline-unresolved` — a type fell back to `any`). Plain `strict: true` / `--strict` fails on both, unchanged from before. Pass `strict: "errors"` (or `--strict=errors`) to fail CI only on `error`-severity diagnostics, letting `any`-fallback warnings through:
+Each diagnostic's `severity` is `"error"` (`example-compile-error`, `example-syntax-error`, `syntax-skipped`, `extend-props-target-missing`, `internal-typedef-referenced` — sveld emitted broken or unmodeled output) or `"warning"` (`prop-unknown-type`, `context-any-type`, `slot-missing-type`, `event-no-source`, `dispatch-escapes`, `rest-props-unresolved`, `context-duplicate-key`, `context-key-unresolved`, `spread-unresolved`, `export-unresolved`, `module-export-conflict`, `extend-props-duplicate`, `extend-props-override`, `jsdoc-unknown-tag`, `typedef-duplicate`, `property-duplicate`, `generics-conflict`, `event-description-ambiguous`, `jsdoc-tag-dropped`, `types-inline-unresolved` — a type fell back to `any`). Plain `strict: true` / `--strict` fails on both, unchanged from before. Pass `strict: "errors"` (or `--strict=errors`) to fail CI only on `error`-severity diagnostics, letting `any`-fallback warnings through:
 
 ```sh
 npx sveld --json --strict=errors
@@ -481,7 +483,7 @@ export default defineConfig({
 });
 ```
 
-**Inline `@sveld-ignore <code>`**, on the same JSDoc comment as the prop, `@event` tag, or context variable it applies to:
+**Inline `@sveld-ignore <code>`**, on the same JSDoc comment as the prop, `@event` tag, context variable, or event dispatcher it applies to:
 
 ```svelte
 <script>
@@ -2187,7 +2189,27 @@ Chained references are also resolved:
 count?: number;
 ```
 
-Resolution follows up to 5 levels of indirection. Beyond that, the last resolved identifier name is used as the default value. If the identifier cannot be resolved (e.g., it is imported from another module), the variable name is used as-is.
+Resolution follows up to 5 levels of indirection. Beyond that, the last resolved identifier name is used as the default value.
+
+A named import resolves when the imported module (followed through re-exports) declares it as an `export const` with a string, number, boolean, or static template literal:
+
+```svelte
+<script>
+  // timing.js: export const TOOLTIP_LEAVE_DELAY_MS = 300;
+  import { TOOLTIP_LEAVE_DELAY_MS } from "./timing.js";
+
+  export let leaveDelayMs = TOOLTIP_LEAVE_DELAY_MS;
+</script>
+```
+
+```ts
+/**
+ * @default 300
+ */
+leaveDelayMs?: number;
+```
+
+Any other identifier that cannot be resolved (an `export let`, a computed value, a package import) is used as-is, and its type falls back to `any`.
 
 When an explicit `@default` annotation is provided, it always takes precedence over the resolved value.
 
@@ -2679,6 +2701,16 @@ A description can wrap onto continuation lines, which run until the next tag. In
  */
 ```
 
+A `{type}` can wrap too. The text after its closing `}` and the name is the tag's own description, exactly as if the type fit on one line:
+
+```js
+/**
+ * @property {"ascending"
+ *   | "descending"} [dir] - The next sort direction,
+ *   reported regardless.
+ */
+```
+
 ### `@callback`
 
 The `@callback` tag defines a function type with `@param` and `@returns`, following the [TypeScript JSDoc `@callback` spec](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#callback). Like `@typedef`, callbacks are exported from the generated `.d.ts`.
@@ -2981,6 +3013,28 @@ In Svelte 5 runes components, callback props like `onclick` are props, not event
 
 Use `null` as the value if no event detail is provided.
 
+`sveld` infers events from `dispatch("name")` calls. When the dispatcher is passed to a function imported from a local module, as `helper(dispatch)` or `helper({ dispatch })`, it reads that function too and picks up the events it dispatches:
+
+```js
+// dispatch-open-close.js
+export function createOpenCloseDispatcher(dispatch) {
+  return (open) => dispatch(open ? "open" : "close");
+}
+```
+
+```svelte
+<script>
+  import { createEventDispatcher } from "svelte";
+  import { createOpenCloseDispatcher } from "./dispatch-open-close.js";
+
+  const dispatch = createEventDispatcher();
+  // Types `open` and `close` as `CustomEvent<null>`
+  const notifyOpenChange = createOpenCloseDispatcher(dispatch);
+</script>
+```
+
+This happens when sveld builds the whole library (CLI, `sveld()`, or the Vite plugin), not when parsing a single component on its own. Each event name there must be a string literal, or a conditional between them. The detail is typed from a literal argument and is `any` otherwise, so add an `@event` tag to type it more precisely. When sveld can't follow the dispatcher (a package import, a local function, a computed event name, or a helper that passes the dispatcher on), it reports `sveld/dispatch-escapes`, and you document those events with `@event` tags.
+
 **Signature:**
 
 ```js
@@ -3634,12 +3688,15 @@ The key becomes the `{PascalCase}Context` type name. `sveld` can resolve:
 | Static template literal | `` setContext(`simple-modal`, …) `` | `SimpleModalContext` |
 | `const`-bound string | `const KEY = "simple-modal";`<br>`setContext(KEY, …)` | `SimpleModalContext` |
 | `Symbol()` / `Symbol.for()` | `setContext(Symbol("tabs"), …)` | `TabsContext` |
+| Imported `export const` string | `import { KEY } from "./keys.js";`<br>`setContext(KEY, …)` | `SimpleModalContext` |
 
 `const` identifiers are followed up to 5 levels deep (`const A = "x"; const B = A;`). Only `const` bindings count. `let`, `var`, and props are skipped because they can change at runtime.
 
 Symbol keys take their name from the description: `Symbol("tabs")` and `Symbol.for("tabs")` both become `TabsContext`. For `const ModalKey = Symbol()` with no description, the binding name wins: `ModalKeyContext`.
 
-Anything else (dynamic identifiers, template interpolation, other function calls) logs a warning. No context type is generated.
+An imported key is read from its module, following re-exports, when that module is a relative `.js`/`.ts` file declaring it as `export const KEY = "simple-modal"` (or a static template literal). This works when sveld builds a whole library (CLI, `sveld()`, or the Vite plugin), not when parsing a single component on its own.
+
+Anything else (dynamic identifiers, `let` exports, template interpolation, other function calls) records a `sveld/context-key-unresolved` diagnostic. No context type is generated.
 
 #### Example
 
@@ -3819,7 +3876,7 @@ There are several ways to type contexts:
 
 #### Notes
 
-- Context keys must be statically resolvable: a string literal, a static template literal, a `const`-bound string, or a `Symbol()` / `Symbol.for()` call with a static description. Dynamic expressions (runtime identifiers, template interpolation, other function calls) are skipped with a warning.
+- Context keys must be statically resolvable: a string literal, a static template literal, a `const`-bound string (local or an imported `export const`), or a `Symbol()` / `Symbol.for()` call with a static description. Dynamic expressions (runtime identifiers, template interpolation, other function calls) are skipped with a `sveld/context-key-unresolved` diagnostic.
 - Variables passed to `setContext` should have JSDoc `@type` annotations for accurate types
 - The generated type name follows the pattern: `{PascalCase}Context`. Separators (hyphens, underscores, dots, colons, slashes, spaces) are stripped and each segment is capitalized:
   | Context Key | Generated Type Name |

package/lib/browser.d.ts

@@ -37,6 +37,13 @@ interface PendingCallDefaultCandidate {
     importedName?: string;
 }
 
+interface PendingConstDefaultCandidate {
+    propName: string;
+    location: "props" | "moduleExports";
+    importSource: string;
+    importedName: string;
+}
+
 interface PendingContextKeyCandidate {
     importSource: string;
     importedName: string;
@@ -46,6 +53,23 @@ interface PendingContextKeyCandidate {
     source?: SourceRange;
 }
 
+interface PendingDispatchEscapeCandidate {
+    importSource: string;
+    importedName: string;
+    /** Callee as written, for messages. */
+    calleeText: string;
+    /** Local name of the `createEventDispatcher()` result. */
+    dispatcherName: string;
+    /** Argument position the dispatcher is passed at. */
+    argumentIndex: number;
+    /** Set when passed as an object literal property (`{ dispatch }`): that property's key. */
+    property?: string;
+    /** Source range of the call, when available. */
+    source?: SourceRange;
+    /** `@sveld-ignore sveld/dispatch-escapes` on the dispatcher's declaration. */
+    ignored?: boolean;
+}
+
 interface ParsedComponentTypeScriptMetadata {
     canonicalPropsType?: string;
     canonicalPropNames: string[];
@@ -60,8 +84,17 @@ interface ParsedComponentTypeScriptMetadata {
     referencesComponentGenerics?: boolean;
     /** Unresolved CallExpression defaults for the cross-file pass in `generateBundle`. */
     pendingCallDefaultCandidates?: PendingCallDefaultCandidate[];
+    /** Imported-identifier defaults for the cross-file pass in `generateBundle`. */
+    pendingConstDefaultCandidates?: PendingConstDefaultCandidate[];
     /** Unresolved `setContext` import keys for the cross-file pass in `generateBundle`. */
     pendingContextKeyCandidates?: PendingContextKeyCandidate[];
+    /** Dispatchers passed to imported functions, for the cross-file pass in `generateBundle`. */
+    pendingDispatchEscapeCandidates?: PendingDispatchEscapeCandidate[];
+    /**
+     * `event-no-source` diagnostics held back while the dispatcher escapes to
+     * imported functions: `generateBundle` keeps those the functions don't dispatch.
+     */
+    deferredEventNoSourceDiagnostics?: SveldDiagnostic[];
 }
 
 type SyntaxMode = "legacy" | "runes";
@@ -506,7 +539,7 @@ export class ComponentParser {
     parseSvelteComponent(source: string, diagnostics: ComponentParserDiagnostics): ParsedComponent;
 }
 
-export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "slot-missing-type" | "event-no-source" | "example-compile-error" | "example-syntax-error" | "syntax-skipped" | "rest-props-unresolved" | "context-duplicate-key" | "spread-unresolved" | "export-unresolved" | "module-export-conflict" | "extend-props-target-missing" | "extend-props-duplicate" | "extend-props-override" | "jsdoc-unknown-tag" | "typedef-duplicate" | "property-duplicate" | "generics-conflict" | "event-description-ambiguous" | "jsdoc-tag-dropped" | "internal-typedef-referenced" | "types-inline-unresolved";
+export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "slot-missing-type" | "event-no-source" | "dispatch-escapes" | "example-compile-error" | "example-syntax-error" | "syntax-skipped" | "rest-props-unresolved" | "context-duplicate-key" | "context-key-unresolved" | "spread-unresolved" | "export-unresolved" | "module-export-conflict" | "extend-props-target-missing" | "extend-props-duplicate" | "extend-props-override" | "jsdoc-unknown-tag" | "typedef-duplicate" | "property-duplicate" | "generics-conflict" | "event-description-ambiguous" | "jsdoc-tag-dropped" | "internal-typedef-referenced" | "types-inline-unresolved";
 
 type SveldDiagnosticSeverity = "error" | "warning";