Skip to content

Commit

Permalink
docs: more docs on TS types
Browse files Browse the repository at this point in the history
and a few related changes/enhancements
closes #13940
  • Loading branch information
dummdidumm committed Oct 31, 2024
1 parent 4715dfa commit afda88c
Show file tree
Hide file tree
Showing 4 changed files with 43 additions and 5 deletions.
23 changes: 22 additions & 1 deletion documentation/docs/07-misc/03-typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,13 @@ Using it together with dynamic components to restrict what kinds of component ca
<DynamicComponent prop="foo" />
```

Closely related to the `Component` type is the `ComponentProps` type which extracts the properties a component expects.
> [!LEGACY] In Svelte 4, components were of type `SvelteComponent`
## Component helper types

### ComponentProps

`ComponentProps` extracts the properties a component expects.

```ts
import type { Component, ComponentProps } from 'svelte';
Expand All @@ -211,6 +217,21 @@ function withProps<TComponent extends Component<any>>(
withProps(MyComponent, { foo: 'bar' });
```

### ComponentExports

`ComponentExports` extracts the exports of a component, in other words you can use it to declare its instance type:

```svelte
<script lang="ts">
import type { ComponentExports } from 'svelte';
import { Component } from './Component.svelte';
let component: ComponentExports<typeof Component>;
</script>
<Component bind:this={component} />
```

## Enhancing built-in DOM types

Svelte provides a best effort of all the HTML DOM types that exist. Sometimes you may want to use experimental attributes or custom events coming from an action. In these cases, TypeScript will throw a type error, saying that it does not know these types. If it's a non-experimental standard attribute/event, this may very well be a missing typing from our [HTML typings](https://github.com/sveltejs/svelte/blob/main/packages/svelte/elements.d.ts). In that case, you are welcome to open an issue and/or a PR fixing it.
Expand Down
19 changes: 17 additions & 2 deletions documentation/docs/07-misc/07-v5-migration-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -599,20 +599,35 @@ To declare that a component of a certain type is required:

```svelte
<script lang="ts">
import type { Component } from 'svelte';
import type { ---SvelteComponent--- +++Component+++ } from 'svelte';
import {
ComponentA,
ComponentB
} from 'component-library';
let component: Component<{ foo: string }> = $state(
---let component: typeof SvelteComponent<{ foo: string }>---
+++let component: Component<{ foo: string }>+++ = $state(
Math.random() ? ComponentA : ComponentB
);
</script>
<svelte:component this={component} foo="bar" />
```

To declare the instance type of a component, or in other words its exports:

```svelte
<script lang="ts">
+++import type { ComponentExports } from 'svelte';+++
import { Component } from './Component.svelte';
---let component: Component;---
+++let component: ComponentExports<typeof Component>;+++
</script>
<Component bind:this={component} />
```

The two utility types `ComponentEvents` and `ComponentType` are also deprecated. `ComponentEvents` is obsolete because events are defined as callback props now, and `ComponentType` is obsolete because the new `Component` type is the component type already (e.g. `ComponentType<SvelteComponent<{ prop: string }>>` == `Component<{ prop: string }>`).

### bind:this changes
Expand Down
3 changes: 2 additions & 1 deletion packages/svelte/src/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,8 @@ export type ComponentProps<Comp extends SvelteComponent | Component<any, any>> =
* Convenience type to get the properties that given component exports.
*
* Example: Typing the `bind:this` for a component named `MyComponent`
* ```
*
* ```ts
* <script lang="ts">
* import MyComponent from '$lib/component';
* let component: ComponentExports<typeof MyComponent> | undefined = undefined;
Expand Down
3 changes: 2 additions & 1 deletion packages/svelte/types/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,8 @@ declare module 'svelte' {
* Convenience type to get the properties that given component exports.
*
* Example: Typing the `bind:this` for a component named `MyComponent`
* ```
*
* ```ts
* <script lang="ts">
* import MyComponent from '$lib/component';
* let component: ComponentExports<typeof MyComponent> | undefined = undefined;
Expand Down

0 comments on commit afda88c

Please sign in to comment.