more

Rich-Harris · Rich-Harris · commit c6f51d8f59c4 · 2024-10-22T01:19:19.000-04:00
diff --git a/documentation/docs/05-special-elements/01-svelte-window.md b/documentation/docs/05-special-elements/01-svelte-window.md
@@ -0,0 +1,44 @@
+---
+title: <svelte:window>
+---
+
+```svelte
+<svelte:window onevent={handler} />
+```
+
+```svelte
+<svelte:window bind:prop={value} />
+```
+
+The `<svelte:window>` element allows you to add event listeners to the `window` object without worrying about removing them when the component is destroyed, or checking for the existence of `window` when server-side rendering.
+
+This element may only appear at the top level of your component — it cannot be inside a block or element.
+
+```svelte
+<script>
+	function handleKeydown(event) {
+		alert(`pressed the ${event.key} key`);
+	}
+</script>
+
+<svelte:window onkeydown={handleKeydown} />
+```
+
+You can also bind to the following properties:
+
+- `innerWidth`
+- `innerHeight`
+- `outerWidth`
+- `outerHeight`
+- `scrollX`
+- `scrollY`
+- `online` — an alias for `window.navigator.onLine`
+- `devicePixelRatio`
+
+All except `scrollX` and `scrollY` are readonly.
+
+```svelte
+<svelte:window bind:scrollY={y} />
+```
+
+> [!NOTE] Note that the page will not be scrolled to the initial value to avoid accessibility issues. Only subsequent changes to the bound variable of `scrollX` and `scrollY` will cause scrolling. If you have a legitimate reason to scroll when the component is rendered, call `scrollTo()` in an `$effect`.
diff --git a/documentation/docs/05-special-elements/02-svelte-document.md b/documentation/docs/05-special-elements/02-svelte-document.md
@@ -0,0 +1,28 @@
+---
+title: <svelte:document>
+---
+
+```svelte
+<svelte:document onevent={handler} />
+```
+
+```svelte
+<svelte:document bind:prop={value} />
+```
+
+Similarly to `<svelte:window>`, this element allows you to add listeners to events on `document`, such as `visibilitychange`, which don't fire on `window`. It also lets you use [actions](use) on `document`.
+
+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 onvisibilitychange={handleVisibilityChange} use:someAction />
+```
+
+You can also bind to the following properties:
+
+- `activeElement`
+- `fullscreenElement`
+- `pointerLockElement`
+- `visibilityState`
+
+All are readonly.
diff --git a/documentation/docs/05-special-elements/03-svelte-body.md b/documentation/docs/05-special-elements/03-svelte-body.md
@@ -0,0 +1,15 @@
+---
+title: <svelte:body>
+---
+
+```svelte
+<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](use) 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 onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction />
+```
diff --git a/documentation/docs/05-special-elements/04-svelte-head.md b/documentation/docs/05-special-elements/04-svelte-head.md
@@ -0,0 +1,18 @@
+---
+title: <svelte:head>
+---
+
+```svelte
+<svelte:head>...</svelte:head>
+```
+
+This element makes it possible to insert elements into `document.head`. During server-side rendering, `head` content is exposed separately to the main `body` content.
+
+As with `<svelte:window>`, `<svelte:document>` and `<svelte:body>`, this element may only appear at the top level of your component and must never be inside a block or element.
+
+```svelte
+<svelte:head>
+	<title>Hello world!</title>
+	<meta name="description" content="This is where the description goes for SEO" />
+</svelte:head>
+```
diff --git a/documentation/docs/05-special-elements/05-svelte-element.md b/documentation/docs/05-special-elements/05-svelte-element.md
@@ -0,0 +1,31 @@
+---
+title: <svelte:element>
+---
+
+```svelte
+<svelte:element this={expression} />
+```
+
+The `<svelte:element>` element lets you render an element that is unknown at author time, for example because it comes from a CMS. Any properties and event listeners present will be applied to the element.
+
+The only supported binding is `bind:this`, since Svelte's built-in bindings do not work with generic elements.
+
+If `this` has a nullish value, the element and its children will not be rendered.
+
+If `this` is the name of a [void element](https://developer.mozilla.org/en-US/docs/Glossary/Void_element) (e.g., `br`) and `<svelte:element>` has child elements, a runtime error will be thrown in development mode:
+
+```svelte
+<script>
+	let tag = $state('hr');
+</script>
+
+<svelte:element this={tag}>
+	This text cannot appear inside an hr element
+</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:
+
+```svelte
+<svelte:element this={tag} xmlns="http://www.w3.org/2000/svg" />
+```
diff --git a/documentation/docs/05-special-elements/06-svelte-options.md b/documentation/docs/05-special-elements/06-svelte-options.md
@@ -0,0 +1,22 @@
+---
+title: <svelte:element>
+---
+
+```svelte
+<svelte:options option={value} />
+```
+
+The `<svelte:options>` element provides a place to specify per-component compiler options, which are detailed in the [compiler section](svelte-compiler#compile). The possible options are:
+
+- `immutable={true}` — you never use mutable data, so the compiler can do simple referential equality checks to determine if values have changed
+- `immutable={false}` — the default. Svelte will be more conservative about whether or not mutable objects have changed
+- `accessors={true}` — adds getters and setters for the component's props
+- `accessors={false}` — the default
+- `runes={true}` — forces a component into _runes mode_ (see the [Legacy APIs](legacy-overview) section)
+- `runes={false}` — forces a component into _legacy mode_
+- `namespace="..."` — the namespace where this component will be used, most commonly "svg"; use the "foreign" namespace to opt out of case-insensitive attribute names and HTML-specific warnings
+- `customElement={...}` — the [options](custom-elements#Component-options) to use when compiling this component as a custom element. If a string is passed, it is used as the `tag` option
+
+```svelte
+<svelte:options customElement="my-custom-element" />
+```
diff --git a/documentation/docs/05-special-elements/09-special-elements.md b/documentation/docs/05-special-elements/09-special-elements.md
diff --git a/documentation/docs/06-runtime/01-stores.md b/documentation/docs/06-runtime/01-stores.md
@@ -2,9 +2,9 @@
 title: Stores
 ---
 
-- how to use
+<!-- - how to use
 - how to write
-- TODO should the details for the store methods belong to the reference section?
+- TODO should the details for the store methods belong to the reference section? -->
 
 A _store_ is an object that allows reactive access to a value via a simple _store contract_. The [`svelte/store` module](../svelte-store) contains minimal store implementations which fulfil this contract.
 
diff --git a/documentation/docs/06-runtime/02-context.md b/documentation/docs/06-runtime/02-context.md
@@ -2,8 +2,8 @@
 title: Context
 ---
 
-- get/set/hasContext
-- how to use, best practises (like encapsulating them)
+<!-- - get/set/hasContext
+- how to use, best practises (like encapsulating them) -->
 
 Most state is component-level state that lives as long as its component lives. There's also section-wide or app-wide state however, which also needs to be handled somehow.
 
diff --git a/documentation/docs/06-runtime/03-lifecycle-hooks.md b/documentation/docs/06-runtime/03-lifecycle-hooks.md
@@ -2,10 +2,10 @@
 title: Lifecycle hooks
 ---
 
-- onMount/onDestroy
+<!-- - onMount/onDestroy
 - mention that `$effect` might be better for your use case
 - beforeUpdate/afterUpdate with deprecation notice?
-- or skip this entirely and only have it in the reference docs?
+- or skip this entirely and only have it in the reference docs? -->
 
 In Svelte 5, the component lifecycle consists of only two parts: Its creation and its destruction. Everything in-between - when certain state is updated - is not related to the component as a whole, only the parts that need to react to the state change are notified. This is because under the hood the smallest unit of change is actually not a component, it's the (render) effects that the component sets up upon component initialization. Consequently, there's no such thing as a "before update"/"after update" hook.
 
diff --git a/documentation/docs/06-runtime/04-imperative-component-api.md b/documentation/docs/06-runtime/04-imperative-component-api.md
