docs: legacy docs

add docs on old syntax

Author: dummdidumm

documentation/docs/01-introduction/03-svelte-files.md

@@ -50,6 +50,9 @@ A `<script>` tag with a `module` attribute runs once when the module first evalu
 
 You can `export` bindings from this block, and they will become exports of the compiled module. You cannot `export default`, since the default export is the component itself.
 
+> [!LEGACY]
+> In Svelte 4, this script tag was created using `<script context="module">`
+
 ## `<style>`
 
 CSS inside a `<style>` block will be scoped to that component.

documentation/docs/01-introduction/04-svelte-js-files.md

@@ -5,3 +5,6 @@ title: .svelte.js and .svelte.ts files
 Besides `.svelte` files, Svelte also operates on `.svelte.js` and `.svelte.ts` files.
 
 These behave like any other `.js` or `.ts` module, except that you can use runes. This is useful for creating reusable reactive logic, or sharing reactive state across your app.
+
+> [!LEGACY]
+> This is a concept that didn't exist prior to Svelte 5

documentation/docs/02-runes/01-what-are-runes.md

@@ -19,3 +19,6 @@ They differ from normal JavaScript functions in important ways, however:
 - You don't need to import them — they are part of the language
 - They're not values — you can't assign them to a variable or pass them as arguments to a function
 - Just like JavaScript keywords, they are only valid in certain positions (the compiler will help you if you put them in the wrong place)
+
+> [!LEGACY]
+> Runes didn't exist prior to Svelte 5.

documentation/docs/99-legacy/00-legacy-overview.md

@@ -0,0 +1,7 @@
+---
+title: Overview
+---
+
+Svelte 5 came with some significant changes to Svelte's API. These include runes, snippets and event attributes. As a result some of the API known from Svelte 3 and 4 is deprecated and will be removed at some point in the future. It is advised to incrementally migrate towards the new syntax, see the [migration guide](v5-migration-guide) for more info.
+
+That said, this legacy syntax is still available today and can be used side by side with the new syntax. The following pages contain reference documentation of said syntax.

documentation/docs/99-legacy/01-legacy-let.md

@@ -0,0 +1,49 @@
+---
+title: let is reactive
+---
+
+To change component state and trigger a re-render, just assign to a locally declared variable.
+
+Update expressions (`count += 1`) and property assignments (`obj.x = y`) have the same effect.
+
+```svelte
+<script>
+	let count = 0;
+
+	function handleClick() {
+		// calling this function will trigger an
+		// update if the markup references `count`
+		count = count + 1;
+	}
+</script>
+```
+
+Because Svelte's reactivity is based on assignments, using array methods like `.push()` and `.splice()` won't automatically trigger updates. A subsequent assignment is required to trigger the update. This and more details can also be found in the [tutorial](https://learn.svelte.dev/tutorial/updating-arrays-and-objects).
+
+```svelte
+<script>
+	let arr = [0, 1];
+
+	function handleClick() {
+		// this method call does not trigger an update
+		arr.push(2);
+		// this assignment will trigger an update
+		// if the markup references `arr`
+		arr = arr;
+	}
+</script>
+```
+
+Svelte's `<script>` blocks are run only when the component is created, so assignments within a `<script>` block are not automatically run again when a prop updates. If you'd like to track changes to a prop, see the next example in the following section.
+
+```svelte
+<script>
+	export let person;
+	// this will only set `name` on component creation
+	// it will not update when `person` does
+	let { name } = person;
+</script>
+```
+
+> [!NOTE]
+> In Svelte 5+, state is explicitly reactive via the [`$state` rune]($state)

documentation/docs/99-legacy/02-legacy-reactive-statements.md

@@ -0,0 +1,87 @@
+---
+title: $:
+---
+
+Any top-level statement (i.e. not inside a block or a function) can be made reactive by prefixing it with the `$:` [JS label syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label). Reactive statements run after other script code and before the component markup is rendered, whenever the values that they depend on have changed.
+
+```svelte
+<script>
+	export let title;
+	export let person;
+
+	// this will update `document.title` whenever
+	// the `title` prop changes
+	$: document.title = title;
+
+	$: {
+		console.log(`multiple statements can be combined`);
+		console.log(`the current title is ${title}`);
+	}
+
+	// this will update `name` when 'person' changes
+	$: ({ name } = person);
+
+	// don't do this. it will run before the previous line
+	let name2 = name;
+</script>
+```
+
+Only values which directly appear within the `$:` block will become dependencies of the reactive statement. For example, in the code below `total` will only update when `x` changes, but not `y`.
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	let x = 0;
+	let y = 0;
+
+	/** @param {number} value */
+	function yPlusAValue(value) {
+		return value + y;
+	}
+
+	$: total = yPlusAValue(x);
+</script>
+
+Total: {total}
+<button on:click={() => x++}> Increment X </button>
+
+<button on:click={() => y++}> Increment Y </button>
+```
+
+It is important to note that the reactive blocks are ordered via simple static analysis at compile time, and all the compiler looks at are the variables that are assigned to and used within the block itself, not in any functions called by them. This means that `yDependent` will not be updated when `x` is updated in the following example:
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	let x = 0;
+	let y = 0;
+
+	/** @param {number} value */
+	function setY(value) {
+		y = value;
+	}
+
+	$: yDependent = y;
+	$: setY(x);
+</script>
+```
+
+Moving the line `$: yDependent = y` below `$: setY(x)` will cause `yDependent` to be updated when `x` is updated.
+
+If a statement consists entirely of an assignment to an undeclared variable, Svelte will inject a `let` declaration on your behalf.
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	/** @type {number} */
+	export let num;
+
+	// we don't need to declare `squared` and `cubed`
+	// — Svelte does it for us
+	$: squared = num * num;
+	$: cubed = squared * num;
+</script>
+```
+
+> [!NOTE]
+> In Svelte 5+, reactions are handled via the [`$derived`]($derived) and [`$effect`]($effect) runes

documentation/docs/99-legacy/03-legacy-export-let.md

@@ -0,0 +1,63 @@
+---
+title: export let
+---
+
+Svelte uses the `export` keyword to mark a variable declaration as a _property_ or _prop_, which means it becomes accessible to consumers of the component (see the section on [attributes and props](/docs/basic-markup#attributes-and-props) for more information).
+
+```svelte
+<script>
+	export let foo;
+
+	// Values that are passed in as props
+	// are immediately available
+	console.log({ foo });
+</script>
+```
+
+You can specify a default initial value for a prop. It will be used if the component's consumer doesn't specify the prop on the component (or if its initial value is `undefined`) when instantiating the component. Note that if the values of props are subsequently updated, then any prop whose value is not specified will be set to `undefined` (rather than its initial value).
+
+In development mode (see the [compiler options](/docs/svelte-compiler#compile)), a warning will be printed if no default initial value is provided and the consumer does not specify a value. To squelch this warning, ensure that a default initial value is specified, even if it is `undefined`.
+
+```svelte
+<script>
+	export let bar = 'optional default initial value';
+	export let baz = undefined;
+</script>
+```
+
+If you export a `const`, `class` or `function`, it is readonly from outside the component. Functions are valid prop values, however, as shown below.
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	// these are readonly
+	export const thisIs = 'readonly';
+
+	/** @param {string} name */
+	export function greet(name) {
+		alert(`hello ${name}!`);
+	}
+
+	// this is a prop
+	export let format = (n) => n.toFixed(2);
+</script>
+```
+
+Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](/docs/component-directives#bind-this).
+
+You can use reserved words as prop names.
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	/** @type {string} */
+	let className;
+
+	// creates a `class` property, even
+	// though it is a reserved word
+	export { className as class };
+</script>
+```
+
+> [!NOTE]
+> In Svelte 5+, use the [`$props`]($props) rune instead

documentation/docs/99-legacy/04-legacy-$$props.md

@@ -0,0 +1,12 @@
+---
+title: $$props
+---
+
+`$$props` references all props that are passed to a component, including ones that are not declared with `export`. Using `$$props` will not perform as well as references to a specific prop because changes to any prop will cause Svelte to recheck all usages of `$$props`. But it can be useful in some cases – for example, when you don't know at compile time what props might be passed to a component.
+
+```svelte
+<Widget {...$$props} />
+```
+
+> [!NOTE]
+> In Svelte 5+, this concept is unnecessary as you can use [`let prop = $props()`]($props) instead

documentation/docs/99-legacy/05-legacy-$$restProps.md

@@ -0,0 +1,12 @@
+---
+title: $$restProps
+---
+
+`$$restProps` contains only the props which are _not_ declared with `export`. It can be used to pass down other unknown attributes to an element in a component. It shares the same performance characteristics compared to specific property access as `$$props`.
+
+```svelte
+<input {...$$restProps} />
+```
+
+> [!NOTE]
+> In Svelte 5+, this concept is unnecessary as you can use [`let { foo, ...rest } = $props()`]($props) instead

documentation/docs/99-legacy/10-legacy-on.md

@@ -0,0 +1,129 @@
+---
+title: on:
+---
+
+```svelte
+<!--- copy: false --->
+on:eventname={handler}
+```
+
+```svelte
+<!--- copy: false --->
+on:eventname|modifiers={handler}
+```
+
+Use the `on:` directive to listen to DOM events.
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	let count = 0;
+
+	/** @param {MouseEvent} event */
+	function handleClick(event) {
+		count += 1;
+	}
+</script>
+
+<button on:click={handleClick}>
+	count: {count}
+</button>
+```
+
+Handlers can be declared inline with no performance penalty. As with attributes, directive values may be quoted for the sake of syntax highlighters.
+
+```svelte
+<button on:click={() => (count += 1)}>
+	count: {count}
+</button>
+```
+
+Add _modifiers_ to DOM events with the `|` character.
+
+```svelte
+<form on:submit|preventDefault={handleSubmit}>
+	<!-- the `submit` event's default is prevented,
+	     so the page won't reload -->
+</form>
+```
+
+The following modifiers are available:
+
+- `preventDefault` — calls `event.preventDefault()` before running the handler
+- `stopPropagation` — calls `event.stopPropagation()`, preventing the event reaching the next element
+- `stopImmediatePropagation` - calls `event.stopImmediatePropagation()`, preventing other listeners of the same event from being fired.
+- `passive` — improves scrolling performance on touch/wheel events (Svelte will add it automatically where it's safe to do so)
+- `nonpassive` — explicitly set `passive: false`
+- `capture` — fires the handler during the _capture_ phase instead of the _bubbling_ phase
+- `once` — remove the handler after the first time it runs
+- `self` — only trigger handler if `event.target` is the element itself
+- `trusted` — only trigger handler if `event.isTrusted` is `true`. I.e. if the event is triggered by a user action.
+
+Modifiers can be chained together, e.g. `on:click|once|capture={...}`.
+
+If the `on:` directive is used without a value, the component will _forward_ the event, meaning that a consumer of the component can listen for it.
+
+```svelte
+<button on:click> The component itself will emit the click event </button>
+```
+
+It's possible to have multiple event listeners for the same event:
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	let counter = 0;
+	function increment() {
+		counter = counter + 1;
+	}
+
+	/** @param {MouseEvent} event */
+	function track(event) {
+		trackEvent(event);
+	}
+</script>
+
+<button on:click={increment} on:click={track}>Click me!</button>
+```
+
+> [!NOTE]
+> In Svelte 5+, use event attributes instead
+> ```svelte
+> <button onclick={() => alert('clicked')}>click me</button>
+> ```
+
+## Component events
+
+Component events created with [`createEventDispatcher`](svelte#createEventDispatcher) create a `CustomEvent`. These events do not bubble. The detail argument corresponds to the `CustomEvent.detail` property and can contain any type of data.
+
+```svelte
+<script>
+	import { createEventDispatcher } from 'svelte';
+
+	const dispatch = createEventDispatcher();
+</script>
+
+<button on:click={() => dispatch('notify', 'detail value')}>Fire Event</button>
+```
+
+Events dispatched from child components can be listened to in their parent. Any data provided when the event was dispatched is available on the `detail` property of the event object.
+
+```svelte
+<script>
+	function callbackFunction(event) {
+		console.log(`Notify fired! Detail: ${event.detail}`);
+	}
+</script>
+
+<Child on:notify={callbackFunction} />
+```
+
+> [!NOTE]
+> If you're planning on migrating to Svelte 5, use callback props instead. This will make upgrading easier as `createEventDispatcher` is deprecated
+> ```svelte
+> <script>
+> 	export let notify;
+> </script>
+> 
+> <button on:click={() => notify('detail value')}>Fire Event</button>
+> ```