From f20d9554b751ea655d7f17d9e01697b5161db937 Mon Sep 17 00:00:00 2001
From: Cameron Messinides <cameron.messinides@gmail.com>
Date: Sat, 15 Aug 2020 17:48:11 -0400
Subject: [PATCH] site: add documentation for $$slots

---
 site/content/docs/02-template-syntax.md       | 21 +++++++++
 .../04-optional-slots/app-a/App.svelte        | 14 ++++++
 .../app-a/ContactCard.svelte                  | 47 +++++++++++++++++++
 .../04-optional-slots/app-b/App.svelte        | 14 ++++++
 .../app-b/ContactCard.svelte                  | 47 +++++++++++++++++++
 .../14-composition/04-optional-slots/text.md  | 25 ++++++++++
 .../app-a/App.svelte                          |  0
 .../app-a/Hoverable.svelte                    |  0
 .../app-b/App.svelte                          |  0
 .../app-b/Hoverable.svelte                    |  0
 .../{04-slot-props => 05-slot-props}/text.md  |  0
 11 files changed, 168 insertions(+)
 create mode 100644 site/content/tutorial/14-composition/04-optional-slots/app-a/App.svelte
 create mode 100644 site/content/tutorial/14-composition/04-optional-slots/app-a/ContactCard.svelte
 create mode 100644 site/content/tutorial/14-composition/04-optional-slots/app-b/App.svelte
 create mode 100644 site/content/tutorial/14-composition/04-optional-slots/app-b/ContactCard.svelte
 create mode 100644 site/content/tutorial/14-composition/04-optional-slots/text.md
 rename site/content/tutorial/14-composition/{04-slot-props => 05-slot-props}/app-a/App.svelte (100%)
 rename site/content/tutorial/14-composition/{04-slot-props => 05-slot-props}/app-a/Hoverable.svelte (100%)
 rename site/content/tutorial/14-composition/{04-slot-props => 05-slot-props}/app-b/App.svelte (100%)
 rename site/content/tutorial/14-composition/{04-slot-props => 05-slot-props}/app-b/Hoverable.svelte (100%)
 rename site/content/tutorial/14-composition/{04-slot-props => 05-slot-props}/text.md (100%)

diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index cfc7d7ba7a..e2d01bba89 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -1289,6 +1289,27 @@ Named slots allow consumers to target specific areas. They can also have fallbac
 </div>
 ```
 
+---
+
+`$$slots` is an object whose keys are the names of the slots passed into the component by the parent. If the parent leaves a named slot empty, `$$slots` will not have a key for that slot. This allows components to render a slot (and other elements, like wrappers for styling) only if the parent provides children for it.
+
+```sv
+<!-- App.svelte -->
+<Card>
+	<h1 slot="title">Blog Post Title</h1>
+</Card>
+
+<!-- Card.svelte -->
+<div>
+	<slot name="title"></slot>
+	{#if $$slots.description}
+		<!-- This slot and the <hr> before it will not render. -->
+		<hr>
+		<slot name="description"></slot>
+	{/if}
+</div>
+```
+
 #### [`<slot let:`*name*`={`*value*`}>`](slot_let)
 
 ---
diff --git a/site/content/tutorial/14-composition/04-optional-slots/app-a/App.svelte b/site/content/tutorial/14-composition/04-optional-slots/app-a/App.svelte
new file mode 100644
index 0000000000..620b602eca
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-a/App.svelte
@@ -0,0 +1,14 @@
+<script>
+	import ContactCard from './ContactCard.svelte';
+</script>
+
+<ContactCard>
+	<span slot="name">
+		P. Sherman
+	</span>
+
+	<span slot="address">
+		42 Wallaby Way<br>
+		Sydney
+	</span>
+</ContactCard>
\ No newline at end of file
diff --git a/site/content/tutorial/14-composition/04-optional-slots/app-a/ContactCard.svelte b/site/content/tutorial/14-composition/04-optional-slots/app-a/ContactCard.svelte
new file mode 100644
index 0000000000..1acf290943
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-a/ContactCard.svelte
@@ -0,0 +1,47 @@
+<style>
+	.contact-card {
+		width: 300px;
+		border: 1px solid #aaa;
+		border-radius: 2px;
+		box-shadow: 2px 2px 8px rgba(0,0,0,0.1);
+		padding: 1em;
+	}
+
+	h2 {
+		padding: 0 0 0.2em 0;
+		margin: 0 0 1em 0;
+		border-bottom: 1px solid #ff3e00
+	}
+
+	.address, .email {
+		padding: 0 0 0 1.5em;
+		background:  0 0 no-repeat;
+		background-size: 20px 20px;
+		margin: 0 0 0.5em 0;
+		line-height: 1.2;
+	}
+
+	.address { background-image: url(tutorial/icons/map-marker.svg) }
+	.email   { background-image: url(tutorial/icons/email.svg) }
+	.missing { color: #999 }
+</style>
+
+<article class="contact-card">
+	<h2>
+		<slot name="name">
+			<span class="missing">Unknown name</span>
+		</slot>
+	</h2>
+
+	<div class="address">
+		<slot name="address">
+			<span class="missing">Unknown address</span>
+		</slot>
+	</div>
+
+	<div class="email">
+		<slot name="email">
+			<span class="missing">Unknown email</span>
+		</slot>
+	</div>
+</article>
\ No newline at end of file
diff --git a/site/content/tutorial/14-composition/04-optional-slots/app-b/App.svelte b/site/content/tutorial/14-composition/04-optional-slots/app-b/App.svelte
new file mode 100644
index 0000000000..aa6d225905
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-b/App.svelte
@@ -0,0 +1,14 @@
+<script>
+	import ContactCard from './ContactCard.svelte';
+</script>
+
+<ContactCard>
+	<span slot="name">
+		P. Sherman
+	</span>
+
+	<span slot="address">
+		42 Wallaby Way<br>
+		Sydney
+	</span>
+</ContactCard>
diff --git a/site/content/tutorial/14-composition/04-optional-slots/app-b/ContactCard.svelte b/site/content/tutorial/14-composition/04-optional-slots/app-b/ContactCard.svelte
new file mode 100644
index 0000000000..9bdb48953b
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-b/ContactCard.svelte
@@ -0,0 +1,47 @@
+<style>
+	.contact-card {
+		width: 300px;
+		border: 1px solid #aaa;
+		border-radius: 2px;
+		box-shadow: 2px 2px 8px rgba(0,0,0,0.1);
+		padding: 1em;
+	}
+
+	h2 {
+		padding: 0 0 0.2em 0;
+		margin: 0 0 1em 0;
+		border-bottom: 1px solid #ff3e00
+	}
+
+	.address, .email {
+		padding: 0 0 0 1.5em;
+		background:  0 0 no-repeat;
+		background-size: 20px 20px;
+		margin: 0 0 0.5em 0;
+		line-height: 1.2;
+	}
+
+	.address { background-image: url(tutorial/icons/map-marker.svg) }
+	.email   { background-image: url(tutorial/icons/email.svg) }
+	.missing { color: #999 }
+</style>
+
+<article class="contact-card">
+	<h2>
+		<slot name="name">
+			<span class="missing">Unknown name</span>
+		</slot>
+	</h2>
+
+	{#if $$slots.address}
+		<div class="address">
+			<slot name="address"></slot>
+		</div>
+	{/if}
+
+	{#if $$slots.email}
+		<div class="email">
+			<slot name="email"></slot>
+		</div>
+	{/if}
+</article>
diff --git a/site/content/tutorial/14-composition/04-optional-slots/text.md b/site/content/tutorial/14-composition/04-optional-slots/text.md
new file mode 100644
index 0000000000..8d095bc211
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/text.md
@@ -0,0 +1,25 @@
+---
+title: Optional slots
+---
+
+In the previous example, the contact card rendered fallback text if a named slot was left empty. But for some slots, perhaps you don't want to render anything at all. We can do this by checking the properties of the special `$$slots` variable.
+
+`$$slots` is an object whose keys are the names of the slots passed in by the parent component. If the parent leaves a slot empty, then `$$slots` will not have an entry for that slot.
+
+In `ContactCard.svelte`, wrap the `address` and `email` slots in `if` blocks that check `$$slots`, and remove the fallbacks from each `<slot>`:
+
+```html
+{#if $$slots.address}
+	<div class="address">
+		<slot name="address"></slot>
+	</div>
+{/if}
+
+{#if $$slots.email}
+	<div class="email">
+		<slot name="email"></slot>
+	</div>
+{/if}
+```
+
+Now the email row won't render at all when the `<App>` leaves that slot empty.
diff --git a/site/content/tutorial/14-composition/04-slot-props/app-a/App.svelte b/site/content/tutorial/14-composition/05-slot-props/app-a/App.svelte
similarity index 100%
rename from site/content/tutorial/14-composition/04-slot-props/app-a/App.svelte
rename to site/content/tutorial/14-composition/05-slot-props/app-a/App.svelte
diff --git a/site/content/tutorial/14-composition/04-slot-props/app-a/Hoverable.svelte b/site/content/tutorial/14-composition/05-slot-props/app-a/Hoverable.svelte
similarity index 100%
rename from site/content/tutorial/14-composition/04-slot-props/app-a/Hoverable.svelte
rename to site/content/tutorial/14-composition/05-slot-props/app-a/Hoverable.svelte
diff --git a/site/content/tutorial/14-composition/04-slot-props/app-b/App.svelte b/site/content/tutorial/14-composition/05-slot-props/app-b/App.svelte
similarity index 100%
rename from site/content/tutorial/14-composition/04-slot-props/app-b/App.svelte
rename to site/content/tutorial/14-composition/05-slot-props/app-b/App.svelte
diff --git a/site/content/tutorial/14-composition/04-slot-props/app-b/Hoverable.svelte b/site/content/tutorial/14-composition/05-slot-props/app-b/Hoverable.svelte
similarity index 100%
rename from site/content/tutorial/14-composition/04-slot-props/app-b/Hoverable.svelte
rename to site/content/tutorial/14-composition/05-slot-props/app-b/Hoverable.svelte
diff --git a/site/content/tutorial/14-composition/04-slot-props/text.md b/site/content/tutorial/14-composition/05-slot-props/text.md
similarity index 100%
rename from site/content/tutorial/14-composition/04-slot-props/text.md
rename to site/content/tutorial/14-composition/05-slot-props/text.md