diff --git a/apps/svelte.dev/.gitignore b/apps/svelte.dev/.gitignore index 4763018f77..d5d05236ed 100644 --- a/apps/svelte.dev/.gitignore +++ b/apps/svelte.dev/.gitignore @@ -9,4 +9,7 @@ /static/svelte-app.json # git-repositories of synced docs go here -/repos/ \ No newline at end of file +/repos/ + +# TODO remove this after https://github.com/sveltejs/kit/pull/12718 is merged +/content/docs/kit/50-reference diff --git a/apps/svelte.dev/content/docs/svelte/02-template-syntax/02-basic-markup.md b/apps/svelte.dev/content/docs/svelte/02-template-syntax/02-basic-markup.md index 8bf9b2cf42..437e59eb14 100644 --- a/apps/svelte.dev/content/docs/svelte/02-template-syntax/02-basic-markup.md +++ b/apps/svelte.dev/content/docs/svelte/02-template-syntax/02-basic-markup.md @@ -112,7 +112,7 @@ Because events are just attributes, the same rules as for attributes apply: Timing-wise, event attributes always fire after events from bindings (e.g. `oninput` always fires after an update to `bind:value`). Under the hood, some event handlers are attached directly with `addEventListener`, while others are _delegated_. -When using `onwheel`, `onmousewheel`, `ontouchstart` and `ontouchmove` event attributes, the handlers are [passive](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) to align with browser defaults. This greatly improves responsiveness by allowing the browser to scroll the document immediately, rather than waiting to see if the event handler calls `event.preventDefault()`. +When using `ontouchstart` and `ontouchmove` event attributes, the handlers are [passive](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) for better performance. This greatly improves responsiveness by allowing the browser to scroll the document immediately, rather than waiting to see if the event handler calls `event.preventDefault()`. In the very rare cases that you need to prevent these event defaults, you should use [`on`](https://svelte-5-preview.vercel.app/docs/imports#svelte-events) instead (for example inside an action). diff --git a/apps/svelte.dev/content/docs/svelte/02-template-syntax/08-bindings.md b/apps/svelte.dev/content/docs/svelte/02-template-syntax/08-bindings.md index 73b49cdd0e..cabbc45969 100644 --- a/apps/svelte.dev/content/docs/svelte/02-template-syntax/08-bindings.md +++ b/apps/svelte.dev/content/docs/svelte/02-template-syntax/08-bindings.md @@ -1,4 +1,4 @@ ---- +--- title: Bindings --- @@ -42,25 +42,34 @@ Numeric input values are coerced; even though `input.value` is a string as far a ``` -On `` elements with `type="file"`, you can use `bind:files` to get the [`FileList` of selected files](https://developer.mozilla.org/en-US/docs/Web/API/FileList). It is readonly. +On `` elements with `type="file"`, you can use `bind:files` to get the [`FileList` of selected files](https://developer.mozilla.org/en-US/docs/Web/API/FileList). When you want to update the files programmatically, you always need to use a `FileList` object. Currently `FileList` objects cannot be constructed directly, so you need to create a new [`DataTransfer`](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer) object and get `files` from there. ```svelte + + + ``` -If you're using `bind:` directives together with `on:` directives, the order that they're defined in affects the value of the bound variable when the event handler is called. +`FileList` objects also cannot be modified, so if you want to e.g. delete a single file from the list, you need to create a new `DataTransfer` object and add the files you want to keep. + +> `DataTransfer` may not be available in server-side JS runtimes. Leaving the state that is bound to `files` uninitialized prevents potential errors if components are server-side rendered. + +If you're using `bind:` directives together with `on` event attributes, the binding will always fire before the event attribute. ```svelte - console.log('Old value:', value)} - bind:value - on:input={() => console.log('New value:', value)} -/> + console.log('New value:', value)} bind:value /> ``` Here we were binding to the value of a text input, which uses the `input` event. Bindings on other elements may use different events such as `change`. diff --git a/apps/svelte.dev/content/docs/svelte/02-template-syntax/09-special-elements.md b/apps/svelte.dev/content/docs/svelte/02-template-syntax/09-special-elements.md index b2f6e1e134..86fad4fa18 100644 --- a/apps/svelte.dev/content/docs/svelte/02-template-syntax/09-special-elements.md +++ b/apps/svelte.dev/content/docs/svelte/02-template-syntax/09-special-elements.md @@ -14,8 +14,7 @@ It cannot appear at the top level of your markup; it must be inside an if or eac ```svelte {#if count > 0} @@ -56,12 +55,12 @@ If `this` is the name of a [void element](https://developer.mozilla.org/en-US/do ```svelte -Foo +Foo ``` Svelte tries its best to infer the correct namespace from the element's surroundings, but it's not always possible. You can make it explicit with an `xmlns` attribute: @@ -73,7 +72,7 @@ Svelte tries its best to infer the correct namespace from the element's surround ## `` ```svelte - + ``` ```svelte @@ -86,13 +85,12 @@ Unlike ``, this element may only appear at the top level of your co ```svelte - + ``` You can also bind to the following properties: @@ -117,7 +115,7 @@ All except `scrollX` and `scrollY` are readonly. ## `` ```svelte - + ``` ```svelte @@ -129,7 +127,7 @@ Similarly to ``, this element allows you to add listeners to even As with ``, this element may only appear the top level of your component and must never be inside a block or element. ```svelte - + ``` You can also bind to the following properties: @@ -144,7 +142,7 @@ All are readonly. ## `` ```svelte - + ``` Similarly to ``, this element allows you to add listeners to events on `document.body`, such as `mouseenter` and `mouseleave`, which don't fire on `window`. It also lets you use [actions](/docs/element-directives#use-action) on the `` element. @@ -152,7 +150,7 @@ Similarly to ``, this element allows you to add listeners to even As with `` and ``, this element may only appear the top level of your component and must never be inside a block or element. ```svelte - + ``` ## `` diff --git a/apps/svelte.dev/content/docs/svelte/05-misc/03-typescript.md b/apps/svelte.dev/content/docs/svelte/05-misc/03-typescript.md index eb58e89b5c..10f0dd30eb 100644 --- a/apps/svelte.dev/content/docs/svelte/05-misc/03-typescript.md +++ b/apps/svelte.dev/content/docs/svelte/05-misc/03-typescript.md @@ -118,7 +118,7 @@ Components can declare a generic relationship between their properties. One exam select: Item; } - let { items, select } = $props(); + let { items, select }: Props = $props(); {#each items as item} @@ -210,8 +210,8 @@ declare namespace svelteHTML { } // enhance attributes interface HTMLAttributes { - // If you want to use on:beforeinstallprompt - 'on:beforeinstallprompt'?: (event: any) => any; + // If you want to use the beforeinstallprompt event + 'onbeforeinstallprompt'?: (event: any) => any; // If you want to use myCustomAttribute={..} (note: all lowercase) mycustomattribute?: any; // You can replace any with something more specific if you like } diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-events.md b/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-events.md index c9e55deb48..1078efa675 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-events.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-events.md @@ -11,6 +11,52 @@ import { on } from 'svelte/events'; ## on +Attaches an event handler to the window and returns a function that removes the handler. Using this +rather than `addEventListener` will preserve the correct order relative to handlers added declaratively +(with attributes like `onclick`), which use event delegation for performance reasons + +
+ +```ts +// @noErrors +function on( + window: Window, + type: Type, + handler: ( + this: Window, + event: WindowEventMap[Type] + ) => any, + options?: AddEventListenerOptions | undefined +): () => void; +``` + +
+ +## on + +Attaches an event handler to the document and returns a function that removes the handler. Using this +rather than `addEventListener` will preserve the correct order relative to handlers added declaratively +(with attributes like `onclick`), which use event delegation for performance reasons + +
+ +```ts +// @noErrors +function on( + document: Document, + type: Type, + handler: ( + this: Document, + event: DocumentEventMap[Type] + ) => any, + options?: AddEventListenerOptions | undefined +): () => void; +``` + +
+ +## on + Attaches an event handler to an element and returns a function that removes the handler. Using this rather than `addEventListener` will preserve the correct order relative to handlers added declaratively (with attributes like `onclick`), which use event delegation for performance reasons @@ -43,6 +89,32 @@ rather than `addEventListener` will preserve the correct order relative to handl
+```ts +// @noErrors +function on< + Element extends MediaQueryList, + Type extends keyof MediaQueryListEventMap +>( + element: Element, + type: Type, + handler: ( + this: Element, + event: MediaQueryListEventMap[Type] + ) => any, + options?: AddEventListenerOptions | undefined +): () => void; +``` + +
+ +## on + +Attaches an event handler to an element and returns a function that removes the handler. Using this +rather than `addEventListener` will preserve the correct order relative to handlers added declaratively +(with attributes like `onclick`), which use event delegation for performance reasons + +
+ ```ts // @noErrors function on( diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-legacy.md b/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-legacy.md index e2c347fb6e..4497cf7de4 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-legacy.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-legacy.md @@ -6,7 +6,21 @@ title: svelte/legacy ```js // @noErrors -import { asClassComponent, createClassComponent, run } from 'svelte/legacy'; +import { + asClassComponent, + createBubbler, + createClassComponent, + handlers, + nonpassive, + once, + passive, + preventDefault, + run, + self, + stopImmediatePropagation, + stopPropagation, + trusted +} from 'svelte/legacy'; ``` ## asClassComponent @@ -33,6 +47,21 @@ function asClassComponent<
+## createBubbler + +Function to create a `bubble` function that mimic the behavior of `on:click` without handler available in svelte 4. + +
+ +```ts +// @noErrors +function createBubbler(): ( + type: string +) => (event: Event) => boolean; +``` + +
+ ## createClassComponent Takes the same options as a Svelte 4 component and the component function and returns a Svelte 4 compatible component. @@ -57,6 +86,89 @@ function createClassComponent< +## handlers + +Function to mimic the multiple listeners available in svelte 4 + +
+ +```ts +// @noErrors +function handlers( + ...handlers: EventListener[] +): EventListener; +``` + +
+ +## nonpassive + +Substitute for the `nonpassive` event modifier, implemented as an action + +
+ +```ts +// @noErrors +function nonpassive( + node: HTMLElement, + [event, handler]: [ + event: string, + handler: () => EventListener + ] +): void; +``` + +
+ +## once + +Substitute for the `once` event modifier + +
+ +```ts +// @noErrors +function once( + fn: (event: Event, ...args: Array) => void +): (event: Event, ...args: unknown[]) => void; +``` + +
+ +## passive + +Substitute for the `passive` event modifier, implemented as an action + +
+ +```ts +// @noErrors +function passive( + node: HTMLElement, + [event, handler]: [ + event: string, + handler: () => EventListener + ] +): void; +``` + +
+ +## preventDefault + +Substitute for the `preventDefault` event modifier + +
+ +```ts +// @noErrors +function preventDefault( + fn: (event: Event, ...args: Array) => void +): (event: Event, ...args: unknown[]) => void; +``` + +
+ ## run Runs the given function once immediately on the server, and works like `$effect.pre` on the client. @@ -70,4 +182,64 @@ function run(fn: () => void | (() => void)): void; +## self + +Substitute for the `self` event modifier + +
+ +```ts +// @noErrors +function self( + fn: (event: Event, ...args: Array) => void +): (event: Event, ...args: unknown[]) => void; +``` + +
+ +## stopImmediatePropagation + +Substitute for the `stopImmediatePropagation` event modifier + +
+ +```ts +// @noErrors +function stopImmediatePropagation( + fn: (event: Event, ...args: Array) => void +): (event: Event, ...args: unknown[]) => void; +``` + +
+ +## stopPropagation + +Substitute for the `stopPropagation` event modifier + +
+ +```ts +// @noErrors +function stopPropagation( + fn: (event: Event, ...args: Array) => void +): (event: Event, ...args: unknown[]) => void; +``` + +
+ +## trusted + +Substitute for the `trusted` event modifier + +
+ +```ts +// @noErrors +function trusted( + fn: (event: Event, ...args: Array) => void +): (event: Event, ...args: unknown[]) => void; +``` + +
+