docs: sync content (#115)

preserve local changes showing legacy blocks

Author: Rich-Harris

apps/svelte.dev/.gitignore

@@ -9,4 +9,7 @@
 /static/svelte-app.json
 
 # git-repositories of synced docs go here
-/repos/
+/repos/
+
+# TODO remove this after https://github.com/sveltejs/kit/pull/12718 is merged
+/content/docs/kit/50-reference

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).
 

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
 <input type="range" bind:value={num} />
 ```
 
-On `<input>` 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 `<input>` 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
+<script>
+	let files = $state();
+
+	function clear() {
+		files = new DataTransfer().files; // null or undefined does not work
+	}
+</script>
+
 <label for="avatar">Upload a picture:</label>
 <input accept="image/png, image/jpeg" bind:files id="avatar" name="avatar" type="file" />
+<button onclick={clear}>clear</button>
 ```
 
-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
 <script>
 	let value = 'Hello World';
 </script>
 
-<input
-	on:input={() => console.log('Old value:', value)}
-	bind:value
-	on:input={() => console.log('New value:', value)}
-/>
+<input oninput={() => 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`.

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
 <script>
-	/** @type {number} */
-	export let count;
+	let { count } = $props();
 </script>
 
 {#if count > 0}
@@ -56,12 +55,12 @@ If `this` is the name of a [void element](https://developer.mozilla.org/en-US/do
 
 ```svelte
 <script>
-	let tag = 'div';
+	let { handler } = $props();
 
-	export let handler;
+	let tag = $state('div');
 </script>
 
-<svelte:element this={tag} on:click={handler}>Foo</svelte:element>
+<svelte:element this={tag} onclick={handler}>Foo</svelte:element>
 ```
 
 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:window>`
 
 ```svelte
-<svelte:window on:event={handler} />
+<svelte:window onevent={handler} />
 ```
 
 ```svelte
@@ -86,13 +85,12 @@ Unlike `<svelte:self>`, this element may only appear at the top level of your co
 
 ```svelte
 <script>
-	/** @param {KeyboardEvent} event */
 	function handleKeydown(event) {
 		alert(`pressed the ${event.key} key`);
 	}
 </script>
 
-<svelte:window on:keydown={handleKeydown} />
+<svelte:window onkeydown={handleKeydown} />
 ```
 
 You can also bind to the following properties:
@@ -117,7 +115,7 @@ All except `scrollX` and `scrollY` are readonly.
 ## `<svelte:document>`
 
 ```svelte
-<svelte:document on:event={handler} />
+<svelte:document onevent={handler} />
 ```
 
 ```svelte
@@ -129,7 +127,7 @@ Similarly to `<svelte:window>`, this element allows you to add listeners to even
 As with `<svelte:window>`, this element may only appear the top level of your component and must never be inside a block or element.
 
 ```svelte
-<svelte:document on:visibilitychange={handleVisibilityChange} use:someAction />
+<svelte:document onvisibilitychange={handleVisibilityChange} use:someAction />
 ```
 
 You can also bind to the following properties:
@@ -144,15 +142,15 @@ All are readonly.
 ## `<svelte:body>`
 
 ```svelte
-<svelte:body on:event={handler} />
+<svelte:body onevent={handler} />
 ```
 
 Similarly to `<svelte:window>`, 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 `<body>` element.
 
 As with `<svelte:window>` and `<svelte:document>`, this element may only appear the top level of your component and must never be inside a block or element.
 
 ```svelte
-<svelte:body on:mouseenter={handleMouseenter} on:mouseleave={handleMouseleave} use:someAction />
+<svelte:body onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction />
 ```
 
 ## `<svelte:head>`

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();
 </script>
 
 {#each items as item}
@@ -210,8 +210,8 @@ declare namespace svelteHTML {
 	}
 	// enhance attributes
 	interface HTMLAttributes<T> {
-		// 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
 	}

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
+
+<div class="ts-block">
+
+```ts
+// @noErrors
+function on<Type extends keyof WindowEventMap>(
+	window: Window,
+	type: Type,
+	handler: (
+		this: Window,
+		event: WindowEventMap[Type]
+	) => any,
+	options?: AddEventListenerOptions | undefined
+): () => void;
+```
+
+</div>
+
+## 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
+
+<div class="ts-block">
+
+```ts
+// @noErrors
+function on<Type extends keyof DocumentEventMap>(
+	document: Document,
+	type: Type,
+	handler: (
+		this: Document,
+		event: DocumentEventMap[Type]
+	) => any,
+	options?: AddEventListenerOptions | undefined
+): () => void;
+```
+
+</div>
+
+## 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
 
 <div class="ts-block">
 
+```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;
+```
+
+</div>
+
+## 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
+
+<div class="ts-block">
+
 ```ts
 // @noErrors
 function on(