From 4e569d18953458d84a8315c8137bb0105c61a3ed Mon Sep 17 00:00:00 2001
From: Simon H <5968653+dummdidumm@users.noreply.github.com>
Date: Fri, 16 Jun 2023 15:08:05 +0200
Subject: [PATCH] docs: Svelte 3/4 differences (#8740)

note some inline, drive-by-fix in custom element docs
closes #8703
---
 .../docs/02-template-syntax/03-logic-blocks.md     |  2 +-
 .../docs/04-compiler-and-api/01-svelte-compiler.md |  1 +
 .../04-compiler-and-api/04-custom-elements-api.md  | 14 ++++++++++++--
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/documentation/docs/02-template-syntax/03-logic-blocks.md b/documentation/docs/02-template-syntax/03-logic-blocks.md
index 06563afcae..43e7511bf5 100644
--- a/documentation/docs/02-template-syntax/03-logic-blocks.md
+++ b/documentation/docs/02-template-syntax/03-logic-blocks.md
@@ -120,7 +120,7 @@ An each block can also have an `{:else}` clause, which is rendered if the list i
 {/each}
 ```
 
-It is possible to iterate over iterables like `Map` or `Set`. Iterables need to be finite and static (they shouldn't change while being iterated over). Under the hood, they are transformed to an array using `Array.from` before being passed off to rendering. If you're writing performance-sensitive code, try to avoid iterables and use regular arrays as they are more performant.
+Since Svelte 4 it is possible to iterate over iterables like `Map` or `Set`. Iterables need to be finite and static (they shouldn't change while being iterated over). Under the hood, they are transformed to an array using `Array.from` before being passed off to rendering. If you're writing performance-sensitive code, try to avoid iterables and use regular arrays as they are more performant.
 
 ## {#await ...}
 
diff --git a/documentation/docs/04-compiler-and-api/01-svelte-compiler.md b/documentation/docs/04-compiler-and-api/01-svelte-compiler.md
index f46183251c..a16a61b31b 100644
--- a/documentation/docs/04-compiler-and-api/01-svelte-compiler.md
+++ b/documentation/docs/04-compiler-and-api/01-svelte-compiler.md
@@ -78,6 +78,7 @@ The following options can be passed to the compiler. None are required:
 | `cssOutputFilename`  | `null`                                      | A `string` used for your CSS sourcemap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `sveltePath`         | `"svelte"`                                  | The location of the `svelte` package. Any imports from `svelte` or `svelte/[module]` will be modified accordingly.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `namespace`          | `"html"`                                    | The namespace of the element; e.g., `"mathml"`, `"svg"`, `"foreign"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `format`             | `"esm"`                                     | This option only exists in Svelte 3. In Svelte 4 only ESM can be output. `"esm"` creates a JavaScript module (with `import` and `export`). `"cjs"` creates a CommonJS module (with `require` and `module.exports`).                                                                                                                                                                                                                                                                                                                                                           |
 
 The returned `result` object contains the code for your component, along with useful bits of metadata.
 
diff --git a/documentation/docs/04-compiler-and-api/04-custom-elements-api.md b/documentation/docs/04-compiler-and-api/04-custom-elements-api.md
index d6d5ef43ce..12f51b6440 100644
--- a/documentation/docs/04-compiler-and-api/04-custom-elements-api.md
+++ b/documentation/docs/04-compiler-and-api/04-custom-elements-api.md
@@ -5,7 +5,11 @@ title: 'Custom elements API'
 Svelte components can also be compiled to custom elements (aka web components) using the `customElement: true` compiler option. You should specify a tag name for the component using the `<svelte:options>` [element](/docs/special-elements#svelte-options).
 
 ```svelte
+<svelte:options customElement="my-element" />
+
+<!-- in Svelte 3, do this instead:
 <svelte:options tag="my-element" />
+-->
 
 <script>
 	export let name = 'world';
@@ -21,7 +25,9 @@ You can leave out the tag name for any of your inner components which you don't
 // @noErrors
 import MyElement from './MyElement.svelte';
 
-customElements.define('my-element', MyElement);
+customElements.define('my-element', MyElement.element);
+// In Svelte 3, do this instead:
+// customElements.define('my-element', MyElement);
 ```
 
 Once a custom element has been defined, it can be used as a regular DOM element:
@@ -49,7 +55,9 @@ console.log(el.name);
 el.name = 'everybody';
 ```
 
-When constructing a custom element, you can tailor several aspects by defining `customElement` as an object within `<svelte:options>`. This object comprises a mandatory `tag` property for the custom element's name, an optional `shadow` property that can be set to `"none"` to forgo shadow root creation (note that styles are then no longer encapsulated, and you can't use slots), and a `props` option, which offers the following settings:
+## Component options
+
+When constructing a custom element, you can tailor several aspects by defining `customElement` as an object within `<svelte:options>` since Svelte 4. This object comprises a mandatory `tag` property for the custom element's name, an optional `shadow` property that can be set to `"none"` to forgo shadow root creation (note that styles are then no longer encapsulated, and you can't use slots), and a `props` option, which offers the following settings:
 
 - `attribute: string`: To update a custom element's prop, you have two alternatives: either set the property on the custom element's reference as illustrated above or use an HTML attribute. For the latter, the default attribute name is the lowercase property name. Modify this by assigning `attribute: "<desired name>"`.
 - `reflect: boolean`: By default, updated prop values do not reflect back to the DOM. To enable this behavior, set `reflect: true`.
@@ -73,6 +81,8 @@ When constructing a custom element, you can tailor several aspects by defining `
 ...
 ```
 
+## Caveats and limitations
+
 Custom elements can be a useful way to package components for consumption in a non-Svelte app, as they will work with vanilla HTML and JavaScript as well as [most frameworks](https://custom-elements-everywhere.com/). There are, however, some important differences to be aware of:
 
 - Styles are _encapsulated_, rather than merely _scoped_ (unless you set `shadow: "none"`). This means that any non-component styles (such as you might have in a `global.css` file) will not apply to the custom element, including styles with the `:global(...)` modifier