From 169fd8497c6dc97f989ccf5b564f69769f5bf335 Mon Sep 17 00:00:00 2001
From: Cameron Messinides <CMessinides@users.noreply.github.com>
Date: Thu, 29 Oct 2020 16:24:39 -0400
Subject: [PATCH] docs: add documentation for $$slots (#5277)

---
 site/content/docs/02-template-syntax.md       | 25 ++++++++
 .../04-optional-slots/app-a/App.svelte        | 57 +++++++++++++++++
 .../04-optional-slots/app-a/Comment.svelte    | 56 ++++++++++++++++
 .../04-optional-slots/app-a/Project.svelte    | 62 ++++++++++++++++++
 .../04-optional-slots/app-b/App.svelte        | 57 +++++++++++++++++
 .../04-optional-slots/app-b/Comment.svelte    | 56 ++++++++++++++++
 .../04-optional-slots/app-b/Project.svelte    | 64 +++++++++++++++++++
 .../14-composition/04-optional-slots/text.md  | 28 ++++++++
 .../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
 13 files changed, 405 insertions(+)
 create mode 100755 site/content/tutorial/14-composition/04-optional-slots/app-a/App.svelte
 create mode 100755 site/content/tutorial/14-composition/04-optional-slots/app-a/Comment.svelte
 create mode 100755 site/content/tutorial/14-composition/04-optional-slots/app-a/Project.svelte
 create mode 100755 site/content/tutorial/14-composition/04-optional-slots/app-b/App.svelte
 create mode 100755 site/content/tutorial/14-composition/04-optional-slots/app-b/Comment.svelte
 create mode 100755 site/content/tutorial/14-composition/04-optional-slots/app-b/Project.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 d955f650e20a..119488aacc26 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -1317,6 +1317,31 @@ Named slots allow consumers to target specific areas. They can also have fallbac
 </div>
 ```
 
+#### [`$$slots`](slots_object)
+
+---
+
+`$$slots` is an object whose keys are the names of the slots passed into the component by the parent. If the parent does not pass in a slot with a particular name, that name will not be a present in `$$slots`. This allows components to render a slot (and other elements, like wrappers for styling) only if the parent provides it.
+
+Note that explicitly passing in an empty named slot will add that slot's name to `$$slots`. For example, if a parent passes `<div slot="title" />` to a child component, `$$slots.title` will be truthy within the child.
+
+```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 100755
index 000000000000..80a4df59f865
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-a/App.svelte
@@ -0,0 +1,57 @@
+<script>
+	import Project from './Project.svelte'
+	import Comment from './Comment.svelte'
+</script>
+
+<style>
+	h1 {
+		font-weight: 300;
+		margin: 0 1rem;
+	}
+
+	ul {
+		list-style: none;
+		padding: 0;
+		margin: 0.5rem;
+		display: flex;
+	}
+
+	@media (max-width: 600px) {
+		ul {
+			flex-direction: column;
+		}
+	}
+
+	li {
+		padding: 0.5rem;
+		flex: 1 1 50%;
+		min-width: 200px;
+	}
+</style>
+
+<h1>
+	Projects
+</h1>
+
+<ul>
+	<li>
+		<Project
+			title="Add Typescript support"
+			tasksCompleted={25}
+			totalTasks={57}
+		>
+			<div slot="comments">
+				<Comment name="Ecma Script" postedAt={new Date('2020-08-17T14:12:23')}>
+					<p>Those interface tests are now passing.</p>
+				</Comment>
+			</div>
+		</Project>
+	</li>
+	<li>
+		<Project
+			title="Update documentation"
+			tasksCompleted={18}
+			totalTasks={21}
+		/>
+	</li>
+</ul>
diff --git a/site/content/tutorial/14-composition/04-optional-slots/app-a/Comment.svelte b/site/content/tutorial/14-composition/04-optional-slots/app-a/Comment.svelte
new file mode 100755
index 000000000000..8d15ffa882ad
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-a/Comment.svelte
@@ -0,0 +1,56 @@
+<script>
+	export let name;
+	export let postedAt;
+
+	$: avatar = `https://ui-avatars.com/api/?name=${name.replace(/ /g, '+')}&rounded=true&background=ff3e00&color=fff&bold=true`;
+</script>
+
+<style>
+	article {
+		background-color: #fff;
+		border: 1px #ccc solid;
+		border-radius: 4px;
+		padding: 1rem;
+	}
+
+	.header {
+		align-items: center;
+		display: flex;
+	}
+
+	.details {
+		flex: 1 1 auto;
+		margin-left: 0.5rem
+	}
+
+	h4 {
+		margin: 0;
+	}
+
+	time {
+		color: #777;
+		font-size: 0.75rem;
+		text-decoration: underline;
+	}
+
+	.body {
+		margin-top: 0.5rem;
+	}
+
+	.body :global(p) {
+		margin: 0;
+	}
+</style>
+
+<article>
+	<div class="header">
+		<img src={avatar} alt="" height="32" width="32">
+		<div class="details">
+			<h4>{name}</h4>
+			<time datetime={postedAt.toISOString()}>{postedAt.toLocaleDateString()}</time>
+		</div>
+	</div>
+	<div class="body">
+		<slot></slot>
+	</div>
+</article>
diff --git a/site/content/tutorial/14-composition/04-optional-slots/app-a/Project.svelte b/site/content/tutorial/14-composition/04-optional-slots/app-a/Project.svelte
new file mode 100755
index 000000000000..38d19fc6389a
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-a/Project.svelte
@@ -0,0 +1,62 @@
+<script>
+	export let title;
+	export let tasksCompleted = 0;
+	export let totalTasks = 0;
+</script>
+
+<style>
+	article {
+		border: 1px #ccc solid;
+		border-radius: 4px;
+		position: relative;
+	}
+
+	article > div {
+		padding: 1.25rem;
+	}
+
+	article.has-discussion::after {
+		content: '';
+		background-color: #ff3e00;
+		border-radius: 10px;
+		box-shadow: 0 2px 4px rgba(0,0,0,0.2);
+		height: 20px;
+		position: absolute;
+		right: -10px;
+		top: -10px;
+		width: 20px;
+	}
+
+	h2,
+	h3 {
+		margin: 0 0 0.5rem;
+	}
+
+	h3 {
+		font-size: 0.875rem;
+		font-weight: 500;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+	}
+
+	p {
+		color: #777;
+		margin: 0;
+	}
+
+	.discussion {
+		background-color: #eee;
+		border-top: 1px #ccc solid;
+	}
+</style>
+
+<article class:has-discussion={true}>
+	<div>
+		<h2>{title}</h2>
+		<p>{tasksCompleted}/{totalTasks} tasks completed</p>
+	</div>
+	<div class="discussion">
+		<h3>Comments</h3>
+		<slot name="comments"></slot>
+	</div>
+</article>
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 100755
index 000000000000..80a4df59f865
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-b/App.svelte
@@ -0,0 +1,57 @@
+<script>
+	import Project from './Project.svelte'
+	import Comment from './Comment.svelte'
+</script>
+
+<style>
+	h1 {
+		font-weight: 300;
+		margin: 0 1rem;
+	}
+
+	ul {
+		list-style: none;
+		padding: 0;
+		margin: 0.5rem;
+		display: flex;
+	}
+
+	@media (max-width: 600px) {
+		ul {
+			flex-direction: column;
+		}
+	}
+
+	li {
+		padding: 0.5rem;
+		flex: 1 1 50%;
+		min-width: 200px;
+	}
+</style>
+
+<h1>
+	Projects
+</h1>
+
+<ul>
+	<li>
+		<Project
+			title="Add Typescript support"
+			tasksCompleted={25}
+			totalTasks={57}
+		>
+			<div slot="comments">
+				<Comment name="Ecma Script" postedAt={new Date('2020-08-17T14:12:23')}>
+					<p>Those interface tests are now passing.</p>
+				</Comment>
+			</div>
+		</Project>
+	</li>
+	<li>
+		<Project
+			title="Update documentation"
+			tasksCompleted={18}
+			totalTasks={21}
+		/>
+	</li>
+</ul>
diff --git a/site/content/tutorial/14-composition/04-optional-slots/app-b/Comment.svelte b/site/content/tutorial/14-composition/04-optional-slots/app-b/Comment.svelte
new file mode 100755
index 000000000000..8d15ffa882ad
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-b/Comment.svelte
@@ -0,0 +1,56 @@
+<script>
+	export let name;
+	export let postedAt;
+
+	$: avatar = `https://ui-avatars.com/api/?name=${name.replace(/ /g, '+')}&rounded=true&background=ff3e00&color=fff&bold=true`;
+</script>
+
+<style>
+	article {
+		background-color: #fff;
+		border: 1px #ccc solid;
+		border-radius: 4px;
+		padding: 1rem;
+	}
+
+	.header {
+		align-items: center;
+		display: flex;
+	}
+
+	.details {
+		flex: 1 1 auto;
+		margin-left: 0.5rem
+	}
+
+	h4 {
+		margin: 0;
+	}
+
+	time {
+		color: #777;
+		font-size: 0.75rem;
+		text-decoration: underline;
+	}
+
+	.body {
+		margin-top: 0.5rem;
+	}
+
+	.body :global(p) {
+		margin: 0;
+	}
+</style>
+
+<article>
+	<div class="header">
+		<img src={avatar} alt="" height="32" width="32">
+		<div class="details">
+			<h4>{name}</h4>
+			<time datetime={postedAt.toISOString()}>{postedAt.toLocaleDateString()}</time>
+		</div>
+	</div>
+	<div class="body">
+		<slot></slot>
+	</div>
+</article>
diff --git a/site/content/tutorial/14-composition/04-optional-slots/app-b/Project.svelte b/site/content/tutorial/14-composition/04-optional-slots/app-b/Project.svelte
new file mode 100755
index 000000000000..87a1d0c3ac01
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/app-b/Project.svelte
@@ -0,0 +1,64 @@
+<script>
+	export let title;
+	export let tasksCompleted = 0;
+	export let totalTasks = 0;
+</script>
+
+<style>
+	article {
+		border: 1px #ccc solid;
+		border-radius: 4px;
+		position: relative;
+	}
+
+	article > div {
+		padding: 1.25rem;
+	}
+
+	article.has-discussion::after {
+		content: '';
+		background-color: #ff3e00;
+		border-radius: 10px;
+		box-shadow: 0 2px 4px rgba(0,0,0,0.2);
+		height: 20px;
+		position: absolute;
+		right: -10px;
+		top: -10px;
+		width: 20px;
+	}
+
+	h2,
+	h3 {
+		margin: 0 0 0.5rem;
+	}
+
+	h3 {
+		font-size: 0.875rem;
+		font-weight: 500;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+	}
+
+	p {
+		color: #777;
+		margin: 0;
+	}
+
+	.discussion {
+		background-color: #eee;
+		border-top: 1px #ccc solid;
+	}
+</style>
+
+<article class:has-discussion={$$slots.comments}>
+	<div>
+		<h2>{title}</h2>
+		<p>{tasksCompleted}/{totalTasks} tasks completed</p>
+	</div>
+	{#if $$slots.comments}
+		<div class="discussion">
+			<h3>Comments</h3>
+			<slot name="comments"></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 000000000000..b875f4c87d4c
--- /dev/null
+++ b/site/content/tutorial/14-composition/04-optional-slots/text.md
@@ -0,0 +1,28 @@
+---
+title: Checking for slot content
+---
+
+In some cases, you may want to control parts of your component based on whether the parent passes in content for a certain slot. Perhaps you have a wrapper around that slot, and you don't want to render it if the slot is empty. Or perhaps you'd like to apply a class only if the slot is present. You 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.
+
+Notice that both instances of `<Project>` in this example render a container for comments and a notification dot, even though only one has comments. We want to use `$$slots` to make sure we only render these elements when the parent `<App>` passes in content for the `comments` slot.
+
+In `Project.svelte`, update the `class:has-discussion` directive on the `<article>`:
+
+```html
+<article class:has-discussion={$$slots.comments}>
+```
+
+Next, wrap the `comments` slot and its wrapping `<div>` in an `if` block that checks `$$slots`:
+
+```html
+{#if $$slots.comments}
+	<div class="discussion">
+		<h3>Comments</h3>
+		<slot name="comments"></slot>
+	</div>
+{/if}
+```
+
+Now the comments container and the notification dot won't render when `<App>` leaves the `comments` 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