msb-public
/
svelte
mirror of https://github.com/sveltejs/svelte
1
0
Code Issues Projects Releases Wiki Activity

docs: add JSDoc to types module

Browse Source
pull/18341/head
Contributor 21 hours ago
parent 05a3bce6bb
commit 692d17b709
10 changed files with 86 additions and 2 deletions
Show Stats Download Patch File Download Diff File

3
packages/svelte/src/animate/public.d.ts vendored
Unescape View File

@ -1,4 +1,4 @@
// todo: same as Transition, should it be shared?
/** Configuration returned by animation functions. */
export interface AnimationConfig {
delay?: number;
duration?: number;
@ -7,6 +7,7 @@ export interface AnimationConfig {
tick?: (t: number, u: number) => void;
}
/** Options for the `flip` animation. */
export interface FlipParams {
delay?: number;
duration?: number | ((len: number) => number);

3
packages/svelte/src/compiler/phases/scope.js
Unescape View File

@ -85,6 +85,7 @@ const global_constants = {
'Math.SQRT1_2': Math.SQRT1_2
};
/** Represents a variable binding in a component scope. */
export class Binding {
/** @type {Scope} */
scope;
@ -602,6 +603,7 @@ class Evaluation {
}
}
/** Represents a lexical scope in the component, tracking bindings and references. */
export class Scope {
/** @type {ScopeRoot} */
root;
@ -859,6 +861,7 @@ const logical = {
'??': (left, right) => left ?? right
};
/** The root scope of a component, managing all top-level bindings. */
export class ScopeRoot {
/** @type {Set<string>} */
conflicts = new Set();

5
packages/svelte/src/compiler/phases/types.d.ts vendored
Unescape View File

@ -17,6 +17,7 @@ import type {
import type { Scope, ScopeRoot } from './scope.js';
import type { ExpressionMetadata } from './nodes.js';
/** Parsed JavaScript module/script with scope information. */
export interface Js {
ast: Program;
scope: Scope;
@ -24,17 +25,20 @@ export interface Js {
has_await: boolean;
}
/** Parsed template with scope information. */
export interface Template {
ast: AST.Fragment;
scope: Scope;
scopes: Map<AST.SvelteNode, Scope>;
}
/** A reactive `$:` statement with its dependencies and assignments. */
export interface ReactiveStatement {
assignments: Set<Binding>;
dependencies: Binding[];
}
/** Metadata for a declaration that contains an await expression. */
export interface AwaitedDeclaration {
id: Identifier;
has_await: boolean;
@ -68,6 +72,7 @@ export interface Analysis {
pickled_awaits: Set<AwaitExpression>;
}
/** Analysis results specific to a Svelte component. */
export interface ComponentAnalysis extends Analysis {
root: ScopeRoot;
instance: Js;

20
packages/svelte/src/compiler/types/css.d.ts vendored
Unescape View File

@ -1,19 +1,23 @@
import type { AST } from '#compiler';
export namespace _CSS {
/** Base interface for all CSS AST nodes. */
export interface BaseNode {
start: number;
end: number;
}
/** Base interface for CSS stylesheets. */
export interface StyleSheetBase extends BaseNode {
children: Array<Atrule | Rule>;
}
/** A standalone CSS file stylesheet. */
export interface StyleSheetFile extends StyleSheetBase {
type: 'StyleSheetFile';
}
/** A `<style>` block from a Svelte component. */
export interface StyleSheet extends StyleSheetBase {
type: 'StyleSheet';
attributes: any[]; // TODO
@ -26,6 +30,7 @@ export namespace _CSS {
};
}
/** A CSS at-rule (e.g. `@media`, `@keyframes`). */
export interface Atrule extends BaseNode {
type: 'Atrule';
name: string;
@ -33,6 +38,7 @@ export namespace _CSS {
block: Block | null;
}
/** A CSS rule with a selector list and a block of declarations. */
export interface Rule extends BaseNode {
type: 'Rule';
prelude: SelectorList;
@ -109,21 +115,25 @@ export namespace _CSS {
};
}
/** A CSS type selector (e.g. `div`, `span`). */
export interface TypeSelector extends BaseNode {
type: 'TypeSelector';
name: string;
}
/** A CSS ID selector (e.g. `#my-id`). */
export interface IdSelector extends BaseNode {
type: 'IdSelector';
name: string;
}
/** A CSS class selector (e.g. `.my-class`). */
export interface ClassSelector extends BaseNode {
type: 'ClassSelector';
name: string;
}
/** A CSS attribute selector (e.g. `[href]`, `[type="text"]`). */
export interface AttributeSelector extends BaseNode {
type: 'AttributeSelector';
name: string;
@ -132,27 +142,32 @@ export namespace _CSS {
flags: string | null;
}
/** A CSS pseudo-element selector (e.g. `::before`, `::after`). */
export interface PseudoElementSelector extends BaseNode {
type: 'PseudoElementSelector';
name: string;
}
/** A CSS pseudo-class selector (e.g. `:hover`, `:nth-child()`). */
export interface PseudoClassSelector extends BaseNode {
type: 'PseudoClassSelector';
name: string;
args: SelectorList | null;
}
/** A CSS percentage value (e.g. in `@keyframes`). */
export interface Percentage extends BaseNode {
type: 'Percentage';
value: string;
}
/** A CSS nesting selector (`&`). */
export interface NestingSelector extends BaseNode {
type: 'NestingSelector';
name: '&';
}
/** An `nth` value used in pseudo-class selectors like `:nth-child()`. */
export interface Nth extends BaseNode {
type: 'Nth';
value: string;
@ -169,23 +184,26 @@ export namespace _CSS {
| Nth
| NestingSelector;
/** A CSS combinator (e.g. `>`, `~`, `+`, ` `). */
export interface Combinator extends BaseNode {
type: 'Combinator';
name: string;
}
/** A CSS declaration block (the contents between `{` and `}`). */
export interface Block extends BaseNode {
type: 'Block';
children: Array<Declaration | Rule | Atrule>;
}
/** A CSS property declaration (e.g. `color: red`). */
export interface Declaration extends BaseNode {
type: 'Declaration';
property: string;
value: string;
}
// for zimmerframe
/** Any CSS AST node. */
export type Node =
| StyleSheet
| Rule

9
packages/svelte/src/compiler/types/index.d.ts vendored
Unescape View File

@ -49,10 +49,13 @@ export interface CompileResult {
ast: any;
}
/** A compiler warning returned during compilation. */
export interface Warning extends ICompileDiagnostic {}
/** A compiler error thrown or collected during compilation. */
export interface CompileError extends ICompileDiagnostic {}
/** Function that returns a CSS class name for scoped styles. */
export type CssHashGetter = (args: {
name: string;
filename: string;
@ -60,6 +63,7 @@ export type CssHashGetter = (args: {
hash: (input: string) => string;
}) => string;
/** Options for optimizing the compiled output. */
export interface OptimizeOptions {
hydrate?: boolean;
}
@ -243,10 +247,12 @@ export interface ModuleCompileOptions {
// The following two somewhat scary looking types ensure that certain types are required but can be undefined still
/** Module compile options with all fields required (except rootDir). */
export type ValidatedModuleCompileOptions = Omit<Required<ModuleCompileOptions>, 'rootDir'> & {
rootDir: ModuleCompileOptions['rootDir'];
};
/** Compile options with all fields validated and required where applicable. */
export type ValidatedCompileOptions = ValidatedModuleCompileOptions &
Omit<
Required<CompileOptions>,
@ -272,6 +278,7 @@ export type ValidatedCompileOptions = ValidatedModuleCompileOptions &
hmr: CompileOptions['hmr'];
};
/** The kind of a binding in the component scope. */
export type BindingKind =
| 'normal' // A variable that is not in any way special
| 'prop' // A normal prop (possibly reassigned or mutated)
@ -287,6 +294,7 @@ export type BindingKind =
| 'template' // A binding declared in the template, e.g. in an `await` block or `const` tag
| 'static'; // A binding whose value is known to be static (i.e. each index)
/** The kind of a variable declaration. */
export type DeclarationKind =
| 'var'
| 'let'
@ -302,6 +310,7 @@ export type DeclarationKind =
| 'using'
| 'await using';
/** Metadata about a state field in a class component. */
export interface StateField {
type: StateCreationRuneName;
node: PropertyDefinition | AssignmentExpression;

31
packages/svelte/src/compiler/types/template.d.ts vendored
Unescape View File

@ -28,12 +28,14 @@ import type { ExpressionMetadata } from '../phases/nodes';
export type Namespace = 'html' | 'svg' | 'mathml';
export namespace AST {
/** Base interface for all AST nodes, containing position information. */
export interface BaseNode {
type: string;
start: number;
end: number;
}
/** A fragment containing a list of child nodes. */
export interface Fragment {
type: 'Fragment';
nodes: Array<Text | Tag | ElementLike | Block | Comment>;
@ -74,6 +76,7 @@ export namespace AST {
};
}
/** Options provided by `<svelte:options>` in the component. */
export interface SvelteOptions {
// start/end info (needed for warnings and for our Prettier plugin)
start: number;
@ -325,6 +328,7 @@ export namespace AST {
};
}
/** Base interface for all element-like AST nodes. */
export interface BaseElement extends BaseNode {
name: string;
name_loc: SourceLocation;
@ -332,6 +336,7 @@ export namespace AST {
fragment: Fragment;
}
/** A component tag in the template (e.g. `<MyComponent>`). */
export interface Component extends BaseElement {
type: 'Component';
/** @internal */
@ -346,16 +351,19 @@ export namespace AST {
};
}
/** A `<title>` element. */
export interface TitleElement extends BaseElement {
type: 'TitleElement';
name: 'title';
}
/** A `<slot>` element. */
export interface SlotElement extends BaseElement {
type: 'SlotElement';
name: 'slot';
}
/** A standard HTML element (e.g. `<div>`, `<span>`). */
export interface RegularElement extends BaseElement {
type: 'RegularElement';
/** @internal */
@ -373,11 +381,13 @@ export namespace AST {
};
}
/** A `<svelte:body>` element. */
export interface SvelteBody extends BaseElement {
type: 'SvelteBody';
name: 'svelte:body';
}
/** A `<svelte:component>` dynamic component element. */
export interface SvelteComponent extends BaseElement {
type: 'SvelteComponent';
name: 'svelte:component';
@ -393,11 +403,13 @@ export namespace AST {
};
}
/** A `<svelte:document>` element. */
export interface SvelteDocument extends BaseElement {
type: 'SvelteDocument';
name: 'svelte:document';
}
/** A `<svelte:element>` dynamic element. */
export interface SvelteElement extends BaseElement {
type: 'SvelteElement';
name: 'svelte:element';
@ -420,16 +432,19 @@ export namespace AST {
};
}
/** A `<svelte:fragment>` element. */
export interface SvelteFragment extends BaseElement {
type: 'SvelteFragment';
name: 'svelte:fragment';
}
/** A `<svelte:boundary>` element for error boundaries. */
export interface SvelteBoundary extends BaseElement {
type: 'SvelteBoundary';
name: 'svelte:boundary';
}
/** A `<svelte:head>` element. */
export interface SvelteHead extends BaseElement {
type: 'SvelteHead';
name: 'svelte:head';
@ -441,6 +456,7 @@ export namespace AST {
name: 'svelte:options';
}
/** A `<svelte:self>` recursive component element. */
export interface SvelteSelf extends BaseElement {
type: 'SvelteSelf';
name: 'svelte:self';
@ -454,6 +470,7 @@ export namespace AST {
};
}
/** A `<svelte:window>` element. */
export interface SvelteWindow extends BaseElement {
type: 'SvelteWindow';
name: 'svelte:window';
@ -523,6 +540,7 @@ export namespace AST {
};
}
/** A `{#key ...}` block that re-renders when the key expression changes. */
export interface KeyBlock extends BaseNode {
type: 'KeyBlock';
expression: Expression;
@ -533,6 +551,7 @@ export namespace AST {
};
}
/** A `{#snippet ...}` block that defines a reusable template fragment. */
export interface SnippetBlock extends BaseNode {
type: 'SnippetBlock';
expression: Identifier;
@ -548,11 +567,13 @@ export namespace AST {
};
}
/** Base interface for attribute AST nodes. */
export interface BaseAttribute extends BaseNode {
name: string;
name_loc: SourceLocation | null;
}
/** A static or dynamic HTML attribute. */
export interface Attribute extends BaseAttribute {
type: 'Attribute';
/**
@ -568,6 +589,7 @@ export namespace AST {
};
}
/** A spread attribute (e.g. `{...obj}`) on an element. */
export interface SpreadAttribute extends BaseNode {
type: 'SpreadAttribute';
expression: Expression;
@ -577,6 +599,7 @@ export namespace AST {
};
}
/** A `<script>` or `<script module>` block. */
export interface Script extends BaseNode {
type: 'Script';
context: 'default' | 'module';
@ -584,6 +607,7 @@ export namespace AST {
attributes: Attribute[];
}
/** A JavaScript comment found in script blocks or expressions. */
export interface JSComment {
type: 'Line' | 'Block';
value: string;
@ -595,8 +619,10 @@ export namespace AST {
};
}
/** An attribute node or a directive on an element. */
export type AttributeLike = Attribute | SpreadAttribute | Directive;
/** A Svelte directive (e.g. `bind:`, `on:`, `use:`). */
export type Directive =
| AST.AnimateDirective
| AST.BindDirective
@ -607,6 +633,7 @@ export namespace AST {
| AST.TransitionDirective
| AST.UseDirective;
/** A template block (e.g. `{#each}`, `{#if}`, `{#await}`). */
export type Block =
| AST.EachBlock
| AST.IfBlock
@ -614,6 +641,7 @@ export namespace AST {
| AST.KeyBlock
| AST.SnippetBlock;
/** Any element-like AST node (components, regular elements, svelte elements). */
export type ElementLike =
| AST.Component
| AST.TitleElement
@ -631,6 +659,7 @@ export namespace AST {
| AST.SvelteWindow
| AST.SvelteBoundary;
/** A template tag (e.g. `{@render}`, `{@html}`, `{@const}`). */
export type Tag =
| AST.AttachTag
| AST.ConstTag
@ -640,6 +669,7 @@ export namespace AST {
| AST.HtmlTag
| AST.RenderTag;
/** Any node that can appear in the template AST. */
export type TemplateNode =
| AST.Root
| AST.Text
@ -652,6 +682,7 @@ export namespace AST {
| AST.Comment
| Block;
/** Any node in the Svelte AST, including ESTree nodes, template nodes, CSS nodes, and scripts. */
export type SvelteNode = Node | TemplateNode | AST.Fragment | _CSS.Node | Script;
export type { _CSS as CSS };

1
packages/svelte/src/index.d.ts vendored
Unescape View File

@ -300,6 +300,7 @@ interface DispatchOptions {
cancelable?: boolean;
}
/** A strongly-typed event dispatcher for dispatching custom events. */
export interface EventDispatcher<EventMap extends Record<string, any>> {
// Implementation notes:
// - undefined extends X instead of X extends undefined makes this work better with both strict and nonstrict mode

1
packages/svelte/src/motion/private.d.ts vendored
Unescape View File

@ -1,3 +1,4 @@
/** Internal context passed to spring tick calculations. */
export interface TickContext {
inv_mass: number;
dt: number;

6
packages/svelte/src/motion/public.d.ts vendored
Unescape View File

@ -1,11 +1,13 @@
import { Readable, type Unsubscriber } from '../store/public.js';
/** Options for configuring spring physics behavior. */
export interface SpringOptions {
stiffness?: number;
damping?: number;
precision?: number;
}
/** Options for a single spring update. */
export interface SpringUpdateOptions {
/**
* @deprecated Only use this for the spring store; does nothing when set on the Spring class
@ -25,8 +27,10 @@ export interface SpringUpdateOptions {
preserveMomentum?: number;
}
/** A function that computes a new value from the target and current value. */
export type Updater<T> = (target_value: T, value: T) => T;
/** Options for configuring tweened transitions. */
export interface TweenOptions<T> {
delay?: number;
duration?: number | ((from: T, to: T) => number);
@ -38,6 +42,7 @@ export interface TweenOptions<T> {
// this means both the Spring class and the Spring interface are merged into one with some things only
// existing on one side. In Svelte 6, remove the type definition and move the jsdoc onto the class in spring.js
/** Legacy spring store interface. Use the `Spring` class for new code. */
export interface Spring<T> extends Readable<T> {
set(new_value: T, opts?: SpringUpdateOptions): Promise<void>;
/**
@ -113,6 +118,7 @@ export class Spring<T> {
get current(): T;
}
/** A store that smoothly transitions between values using tweens. */
export interface Tweened<T> extends Readable<T> {
set(value: T, opts?: TweenOptions<T>): Promise<void>;
update(updater: Updater<T>, opts?: TweenOptions<T>): Promise<void>;

9
packages/svelte/src/transition/public.d.ts vendored
Unescape View File

@ -1,5 +1,7 @@
/** A function that maps a value between 0 and 1 to an eased value. */
export type EasingFunction = (t: number) => number;
/** Configuration object returned by transition functions. */
export interface TransitionConfig {
delay?: number;
duration?: number;
@ -8,6 +10,7 @@ export interface TransitionConfig {
tick?: (t: number, u: number) => void;
}
/** Parameters for the `blur` transition. */
export interface BlurParams {
delay?: number;
duration?: number;
@ -16,12 +19,14 @@ export interface BlurParams {
opacity?: number;
}
/** Parameters for the `fade` transition. */
export interface FadeParams {
delay?: number;
duration?: number;
easing?: EasingFunction;
}
/** Parameters for the `fly` transition. */
export interface FlyParams {
delay?: number;
duration?: number;
@ -31,6 +36,7 @@ export interface FlyParams {
opacity?: number;
}
/** Parameters for the `slide` transition. */
export interface SlideParams {
delay?: number;
duration?: number;
@ -38,6 +44,7 @@ export interface SlideParams {
axis?: 'x' | 'y';
}
/** Parameters for the `scale` transition. */
export interface ScaleParams {
delay?: number;
duration?: number;
@ -46,6 +53,7 @@ export interface ScaleParams {
opacity?: number;
}
/** Parameters for the `draw` transition (SVG path animation). */
export interface DrawParams {
delay?: number;
speed?: number;
@ -53,6 +61,7 @@ export interface DrawParams {
easing?: EasingFunction;
}
/** Parameters for the `crossfade` transition. */
export interface CrossfadeParams {
delay?: number;
duration?: number | ((len: number) => number);

Write Preview
Loading…
Cancel
Save