From 2466f8414e970e01f6705af512682d4a782d7a49 Mon Sep 17 00:00:00 2001
From: stephane-vanraes <stephane.vanraes@gmail.com>
Date: Thu, 18 Mar 2021 20:57:45 +0100
Subject: [PATCH] Add documentation and tutorial for svelte:fragment

---
 site/content/docs/02-template-syntax.md       | 44 +++++++++++++++++++
 .../08-svelte-fragment/app-a/App.svelte       | 11 +++++
 .../08-svelte-fragment/app-a/Box.svelte       | 20 +++++++++
 .../08-svelte-fragment/app-b/App.svelte       | 11 +++++
 .../08-svelte-fragment/app-b/Box.svelte       | 20 +++++++++
 .../08-svelte-fragment/text.md                | 43 ++++++++++++++++++
 6 files changed, 149 insertions(+)
 create mode 100644 site/content/tutorial/16-special-elements/08-svelte-fragment/app-a/App.svelte
 create mode 100644 site/content/tutorial/16-special-elements/08-svelte-fragment/app-a/Box.svelte
 create mode 100644 site/content/tutorial/16-special-elements/08-svelte-fragment/app-b/App.svelte
 create mode 100644 site/content/tutorial/16-special-elements/08-svelte-fragment/app-b/Box.svelte
 create mode 100644 site/content/tutorial/16-special-elements/08-svelte-fragment/text.md

diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index 2c665376dc..2cd973cf31 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -1328,6 +1328,28 @@ Named slots allow consumers to target specific areas. They can also have fallbac
 </Widget>
 ```
 
+Named slots can also be used with components `<Component slot="name" />`.
+In order to place content in a slot without losing the flow layout (ie: without using a wrapper element) you can use the special element `<svelte:fragment>`.
+
+```sv
+<!-- Widget.svelte -->
+<div>
+	<slot name="header">No header was provided</slot>
+	<p>Some content between header and footer</p>
+	<slot name="footer"></slot>
+</div>
+
+<!-- App.svelte -->
+<Widget>
+	<HeaderComponent slot="header" />
+	<svelte:fragment slot="footer">
+		<p>All rights reserved.</p>
+		<p>Copyright (c) 2019 Svelte Industries</p>
+	</svelte:fragment>
+</Widget>
+```
+
+
 #### [`$$slots`](slots_object)
 
 ---
@@ -1537,3 +1559,25 @@ The `<svelte:options>` element provides a place to specify per-component compile
 ```sv
 <svelte:options tag="my-custom-element"/>
 ```
+
+### `<svelte:fragment>`
+
+The `<svelte:fragment>` allows you to place content in a named [docs](docs#slot_name) without wrapping it in a container, this allows to keep intact the flow layout of your document.
+
+```sv
+<!-- Widget.svelte -->
+<div>
+	<slot name="header">No header was provided</slot>
+	<p>Some content between header and footer</p>
+	<slot name="footer"></slot>
+</div>
+
+<!-- App.svelte -->
+<Widget>
+	<h1 slot="header">Hello</h1>
+	<svelte:fragment slot="footer">
+		<p>All rights reserved.</p>
+		<p>Copyright (c) 2019 Svelte Industries</p>
+	</svelte:fragment>
+</Widget>
+```
diff --git a/site/content/tutorial/16-special-elements/08-svelte-fragment/app-a/App.svelte b/site/content/tutorial/16-special-elements/08-svelte-fragment/app-a/App.svelte
new file mode 100644
index 0000000000..3708b34880
--- /dev/null
+++ b/site/content/tutorial/16-special-elements/08-svelte-fragment/app-a/App.svelte
@@ -0,0 +1,11 @@
+<script>
+	import Box from './Box.svelte'
+</script>
+
+<!-- App.svelte -->
+<Box>
+	<div slot="footer">
+		<p>All rights reserved.</p>
+		<p>Copyright (c) 2019 Svelte Industries</p>
+	</div>
+</Box>
\ No newline at end of file
diff --git a/site/content/tutorial/16-special-elements/08-svelte-fragment/app-a/Box.svelte b/site/content/tutorial/16-special-elements/08-svelte-fragment/app-a/Box.svelte
new file mode 100644
index 0000000000..16c17f90ef
--- /dev/null
+++ b/site/content/tutorial/16-special-elements/08-svelte-fragment/app-a/Box.svelte
@@ -0,0 +1,20 @@
+<style>
+	.box {
+		width: 300px;
+		border: 1px solid #aaa;
+		border-radius: 2px;
+		box-shadow: 2px 2px 8px rgba(0,0,0,0.1);
+		padding: 1em;
+		margin: 0 0 1em 0;
+		
+		display: flex;
+		flex-direction: column;
+		gap: 1em;
+	}
+</style>
+
+<div class="box">
+	<slot name="header">No header was provided</slot>
+	<p>Some content between header and footer</p>
+	<slot name="footer"></slot>
+</div>
diff --git a/site/content/tutorial/16-special-elements/08-svelte-fragment/app-b/App.svelte b/site/content/tutorial/16-special-elements/08-svelte-fragment/app-b/App.svelte
new file mode 100644
index 0000000000..2724752b80
--- /dev/null
+++ b/site/content/tutorial/16-special-elements/08-svelte-fragment/app-b/App.svelte
@@ -0,0 +1,11 @@
+<script>
+	import Box from './Box.svelte'
+</script>
+
+<!-- App.svelte -->
+<Box>
+	<svelte:fragment slot="footer">
+		<p>All rights reserved.</p>
+		<p>Copyright (c) 2019 Svelte Industries</p>
+	</svelte:fragment>
+</Box>
diff --git a/site/content/tutorial/16-special-elements/08-svelte-fragment/app-b/Box.svelte b/site/content/tutorial/16-special-elements/08-svelte-fragment/app-b/Box.svelte
new file mode 100644
index 0000000000..16c17f90ef
--- /dev/null
+++ b/site/content/tutorial/16-special-elements/08-svelte-fragment/app-b/Box.svelte
@@ -0,0 +1,20 @@
+<style>
+	.box {
+		width: 300px;
+		border: 1px solid #aaa;
+		border-radius: 2px;
+		box-shadow: 2px 2px 8px rgba(0,0,0,0.1);
+		padding: 1em;
+		margin: 0 0 1em 0;
+		
+		display: flex;
+		flex-direction: column;
+		gap: 1em;
+	}
+</style>
+
+<div class="box">
+	<slot name="header">No header was provided</slot>
+	<p>Some content between header and footer</p>
+	<slot name="footer"></slot>
+</div>
diff --git a/site/content/tutorial/16-special-elements/08-svelte-fragment/text.md b/site/content/tutorial/16-special-elements/08-svelte-fragment/text.md
new file mode 100644
index 0000000000..8505256955
--- /dev/null
+++ b/site/content/tutorial/16-special-elements/08-svelte-fragment/text.md
@@ -0,0 +1,43 @@
+---
+title: <svelte:fragment>
+---
+
+The `<svelte:fragment>` element allows you to add content to a named slot without breaking the document's flow layout.
+
+In the example notice how we applied a flex layout with a gap of 2em to the box.
+
+```sv
+<!-- Box.svelte -->
+<style>
+	.box {
+		width: 300px;
+		border: 1px solid #aaa;
+		border-radius: 2px;
+		box-shadow: 2px 2px 8px rgba(0,0,0,0.1);
+		padding: 1em;
+		margin: 0 0 1em 0;
+		
+		display: flex;
+		flex-direction: column;
+		gap: 1em;
+	}
+</style>
+
+<div class="box">
+	<slot name="header">No header was provided</slot>
+	<p>Some content between header and footer</p>
+	<slot name="footer"></slot>
+</div>
+```
+
+The content in the footer however is not spaced out according to this rythm because wrapping it in a div created a new flow layout.
+
+We can solve this by changing `<div slot="footer">` in the `App` component:
+
+```sv
+<svelte:fragment slot="footer">
+	<p>All rights reserved.</p>
+	<p>Copyright (c) 2019 Svelte Industries</p>
+</svelte:fragment>
+```
+