sveld 0.37.5 → 0.37.7

package/lib/browser.d.ts

@@ -42,21 +42,52 @@ interface PendingConstDefaultCandidate {
     location: "props" | "moduleExports";
     importSource: string;
     importedName: string;
+    /** Members read off the import, through namespace exports: `["DELAY"]` for `C.timing.DELAY`. */
+    members?: string[];
 }
 
 interface PendingContextKeyCandidate {
     importSource: string;
     importedName: string;
+    /** Members read off the import, through namespace exports: `["THEME"]` for `ns.keys.THEME`. */
+    members?: string[];
+    /** See {@link ComponentContext.type}. */
+    type?: string;
     properties: ComponentContextProp[];
     description?: string;
+    /** See {@link ComponentContext.hasUnresolvedSpread}. */
+    hasUnresolvedSpread?: boolean;
+    /** See {@link ComponentContext.internal}. */
+    internal?: boolean;
     /** Source range of the `setContext(...)` call, when available. */
     source?: SourceRange;
 }
 
+interface PendingDispatchEscapeCandidate {
+    importSource: string;
+    importedName: string;
+    /** Members read off the import, through namespace exports: `["helper"]` for `ns.helper`. */
+    members?: 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[];
     localTypeDeclarations: string[];
+    /** Types the module script exports (`export interface Item`), emitted with `export`. */
+    moduleTypeDeclarations?: string[];
     typeImportStatements: string[];
     /**
      * Whether `canonicalPropsType` mentions one of the component's own
@@ -71,6 +102,18 @@ interface ParsedComponentTypeScriptMetadata {
     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[];
+    /**
+     * `@event` tags with no `{type}` or `@property`, whose `null` detail no
+     * same-file dispatch replaced; an escaped dispatcher's helper may still.
+     */
+    untypedJsDocEventNames?: string[];
 }
 
 type SyntaxMode = "legacy" | "runes";
@@ -126,6 +169,29 @@ interface ComponentPropReExport {
     imported: string;
 }
 
+interface ComponentClassMember {
+    /** `"property"` covers fields, constructor parameter properties, and getter/setter pairs. */
+    kind: "constructor" | "method" | "property";
+    /** Member name; `"constructor"` for the constructor. */
+    name: string;
+    /** Property type text; `"any"` when neither TypeScript nor JSDoc types it. */
+    type?: string;
+    /** Method or constructor parameters, typed from TypeScript or JSDoc `@param`, else `"any"`. A rest parameter's name starts with `...`. */
+    params?: ComponentPropParam[];
+    /** Method return type from TypeScript or JSDoc `@returns`; unset when neither gives one. */
+    returnType?: string;
+    /** A method's own type parameter list (`U extends object`), without the angle brackets. */
+    typeParameters?: string;
+    static?: true;
+    /** A `readonly` field, or a getter with no setter. */
+    readonly?: true;
+    optional?: true;
+    abstract?: true;
+    description?: string;
+    deprecated?: DeprecatedValue;
+    tags?: JsDocPassthroughTag[];
+}
+
 interface ComponentProp {
     /** Public prop name; `"*"` for a bare `export * from "..."`. */
     name: string;
@@ -133,8 +199,10 @@ interface ComponentProp {
      * `"let"` (required), `"const"` (default), or `"function"`. `"re-export"`
      * is module-export only: `export { x } from "..."`, `export * from "..."`,
      * or `export { x }` of an imported binding, written to the `.d.ts` as-is.
+     * `"class"` is module-export only too: a class the module script declares,
+     * with its public surface in {@link ComponentProp.members}.
      */
-    kind: "let" | "const" | "function" | "re-export";
+    kind: "let" | "const" | "function" | "re-export" | "class";
     /** True when declared with `const`. */
     constant: boolean;
     /** TypeScript type text. */
@@ -157,8 +225,17 @@ interface ComponentProp {
      * A function's own type parameter list from its `@template` tags (e.g.
      * `T extends { id: string }`), without the angle brackets. Also prefixed
      * onto `type` when that signature is built from `@param`/`@returns`.
+     * For a `"class"`, the class's type parameters, from TypeScript or `@template`.
      */
     typeParameters?: string;
+    /** Set when `kind` is `"class"`: its public constructor, methods, and properties, in source order. */
+    members?: ComponentClassMember[];
+    /** Set when `kind` is `"class"` and the class is `abstract`. */
+    abstract?: true;
+    /** Set when `kind` is `"class"` and it extends a base class: `Base<T>`. */
+    extends?: string;
+    /** Set when `kind` is `"class"` and it implements interfaces: `["Disposable"]`. */
+    implements?: string[];
     /**
      * True for arrow/function-expression initializers and bare `function`
      * declarations in every mode; additionally true for a function-shaped
@@ -357,9 +434,15 @@ interface ComponentContext {
     key: string;
     /** Generated type name (e.g. `"ModalContext"`). */
     typeName: string;
+    /**
+     * The context's whole type, when the `setContext` value is a variable whose
+     * type isn't an object type literal (`ModalAPI`, `Writable<number>`, or `any`
+     * when untyped). `properties` is empty then.
+     */
+    type?: string;
     /** From JSDoc. */
     description?: string;
-    /** Context object properties. */
+    /** Context object properties. Empty when {@link ComponentContext.type} is set. */
     properties: ComponentContextProp[];
     /** True when a `{...spread}` in the context's object literal couldn't be resolved; the generated type intersects with `Record<string, any>`. */
     hasUnresolvedSpread?: boolean;
@@ -452,13 +535,37 @@ export class ComponentParser {
     } | undefined;
     private addModuleExport;
     /**
-     * Resolves one `export { local as exported }` specifier to the variable
-     * declarator it names. Each specifier resolves on its own, so
+     * Resolves one `export { local as exported }` specifier to the top-level
+     * function, class, or variable declarator (including one destructured
+     * from a pattern) it names. Each specifier resolves on its own, so
      * `export { a, b }` exports both, and `const a = 1, b = ""; export { b }`
      * exports `b`'s declarator rather than the first one in the declaration.
+     *
+     * `program` is the script the export sits in: only its top-level
+     * declarations count, not a same-named variable inside a function. An
+     * instance-script export can also name a module-script declaration, or a
+     * variable that a `$: local = ...` reactive declaration declares implicitly.
      */
     private resolveExportSpecifier;
     private recordUnresolvedExportSpecifier;
+    /**
+     * Doc comment for a declaration exported by `node`. A specifier uses the
+     * comment on the declaration it names. An `export { ... }` list's own
+     * comment documents it too, but only when the list has a single specifier;
+     * its tags and description then override the declaration's.
+     */
+    private exportJSDoc;
+    /** An instance-script `export class Foo {}` or `export { Foo }` of a class: neither a prop nor a documented accessor. */
+    private recordClassExport;
+    /**
+     * The `.d.ts` can only say `extends Base` when `Base` is in scope there:
+     * imported, or another exported class. A class extending anything else
+     * (a local class, a call like `mixin(Base)`) is declared without it, and
+     * flagged, since consumers won't see its inherited members.
+     */
+    private dropUndeclaredClassBases;
+    /** A module-script `export class Foo {}` or `export { Foo }` of a class, with its public members. */
+    private addModuleClassExport;
     /**
      * @example
      * ```ts
@@ -486,6 +593,17 @@ export class ComponentParser {
         description?: string;
         internal?: boolean;
     } | null;
+    /**
+     * The description and `@internal` flag of the JSDoc above `varName`,
+     * whether or not it has a `@type`. For a variable typed some other way,
+     * such as from its initializer.
+     */
+    findVariableJsDoc(varName: string): {
+        description?: string;
+        internal?: boolean;
+    };
+    /** The JSDoc table entry for `varName`, building the table on first use. */
+    private variableJsDocEntry;
     accumulateGeneric(name: string, constraint: string): void;
     /**
      * Resets parser state for reuse between parses.
@@ -499,6 +617,7 @@ export class ComponentParser {
      */
     cleanup(): void;
     private static readonly SCRIPT_BLOCK_REGEX;
+    /** A `// @ts-...` comment, but not one on a `*` line of a JSDoc block (e.g. in an `@example`). */
     private static readonly TS_DIRECTIVE_REGEX;
     private static stripTypeScriptDirectivesFromScripts;
     /**
@@ -515,12 +634,15 @@ 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" | "context-value-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" | "cross-file-unresolved" | "export-ambiguous";
 
 type SveldDiagnosticSeverity = "error" | "warning";
 
 export interface SveldDiagnostic {
-    /** File this came from, e.g. `"./Button.svelte"`. */
+    /**
+     * File this came from, e.g. `"./Button.svelte"`, or the entry barrel
+     * (`"./index.js"`) for `export-ambiguous`.
+     */
     component: string;
     kind: SveldDiagnosticKind;
     /** Stable, namespaced identifier for `kind` (e.g. `"sveld/prop-unknown-type"`). */
@@ -542,6 +664,13 @@ export interface SveldDiagnostic {
 
 declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
 
+export interface FinalizeWithoutCrossFileResolutionOptions {
+    /** Path recorded on the new diagnostics. Defaults to the component's own `filePath`, if it has one. */
+    filePath?: string;
+}
+
+export declare function finalizeWithoutCrossFileResolution<T extends ParsedComponent>(component: T, options?: FinalizeWithoutCrossFileResolutionOptions): T;
+
 export interface ComponentDocApi extends ParsedComponent {
     filePath: NormalizedPath;
     moduleName: string;
@@ -641,7 +770,11 @@ export declare function writeTsDefinition(component: ComponentDocApi, options?:
 interface EntryExport {
     name: string;
     kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
-    /** Type text from the source, when present. */
+    /**
+     * Type text from the source, when present. A namespace export
+     * (`export * as ns from "./x"`) gets `typeof import("./x.ts")`, the
+     * wrapped module relative to the entry file.
+     */
     type?: string;
     /** Initializer text for simple constants. */
     value?: string;