From 449e1502e75077597889c135bfbf35b422ef7204 Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.a.harris@gmail.com>
Date: Sun, 3 Mar 2019 18:43:41 -0500
Subject: [PATCH] document tweened and spring

---
 .../08-motion/01-tweened/app-a/App.svelte     | 30 ++++++++++++++
 .../08-motion/01-tweened/app-b/App.svelte     | 34 ++++++++++++++++
 .../tutorial/08-motion/01-tweened/text.md     | 40 +++++++++++++++++++
 .../08-motion/02-spring/app-a/App.svelte      | 31 ++++++++++++++
 .../08-motion/02-spring/app-b/App.svelte      | 35 ++++++++++++++++
 .../tutorial/08-motion/02-spring/text.md      | 27 +++++++++++++
 site/content/tutorial/08-motion/meta.json     |  3 ++
 site/content/tutorial/99-todo/99-todo/text.md |  4 +-
 8 files changed, 202 insertions(+), 2 deletions(-)
 create mode 100644 site/content/tutorial/08-motion/01-tweened/app-a/App.svelte
 create mode 100644 site/content/tutorial/08-motion/01-tweened/app-b/App.svelte
 create mode 100644 site/content/tutorial/08-motion/01-tweened/text.md
 create mode 100644 site/content/tutorial/08-motion/02-spring/app-a/App.svelte
 create mode 100644 site/content/tutorial/08-motion/02-spring/app-b/App.svelte
 create mode 100644 site/content/tutorial/08-motion/02-spring/text.md
 create mode 100644 site/content/tutorial/08-motion/meta.json

diff --git a/site/content/tutorial/08-motion/01-tweened/app-a/App.svelte b/site/content/tutorial/08-motion/01-tweened/app-a/App.svelte
new file mode 100644
index 0000000000..a9b73e93ac
--- /dev/null
+++ b/site/content/tutorial/08-motion/01-tweened/app-a/App.svelte
@@ -0,0 +1,30 @@
+<script>
+	import { writable } from 'svelte/store';
+
+	const progress = writable(0);
+</script>
+
+<style>
+	progress {
+		display: block;
+		width: 100%;
+	}
+</style>
+
+<progress value={$progress}></progress>
+
+<button on:click="{() => progress.set(0.25)}">
+	25%
+</button>
+
+<button on:click="{() => progress.set(0.5)}">
+	50%
+</button>
+
+<button on:click="{() => progress.set(0.75)}">
+	75%
+</button>
+
+<button on:click="{() => progress.set(1)}">
+	100%
+</button>
\ No newline at end of file
diff --git a/site/content/tutorial/08-motion/01-tweened/app-b/App.svelte b/site/content/tutorial/08-motion/01-tweened/app-b/App.svelte
new file mode 100644
index 0000000000..c64380858e
--- /dev/null
+++ b/site/content/tutorial/08-motion/01-tweened/app-b/App.svelte
@@ -0,0 +1,34 @@
+<script>
+	import { tweened } from 'svelte/motion';
+	import { cubicOut } from 'svelte/easing';
+
+	const progress = tweened(0, {
+		duration: 400,
+		easing: cubicOut
+	});
+</script>
+
+<style>
+	progress {
+		display: block;
+		width: 100%;
+	}
+</style>
+
+<progress value={$progress}></progress>
+
+<button on:click="{() => progress.set(0.25)}">
+	25%
+</button>
+
+<button on:click="{() => progress.set(0.5)}">
+	50%
+</button>
+
+<button on:click="{() => progress.set(0.75)}">
+	75%
+</button>
+
+<button on:click="{() => progress.set(1)}">
+	100%
+</button>
\ No newline at end of file
diff --git a/site/content/tutorial/08-motion/01-tweened/text.md b/site/content/tutorial/08-motion/01-tweened/text.md
new file mode 100644
index 0000000000..23f4147a9d
--- /dev/null
+++ b/site/content/tutorial/08-motion/01-tweened/text.md
@@ -0,0 +1,40 @@
+---
+title: Tweened
+---
+
+Setting values and watching the DOM update automatically is cool. Know what's even cooler? *Tweening* those values. Svelte includes tools to help you build slick user interfaces that use animation to communicate changes.
+
+Let's start by changing the `progress` store to a `tweened` value:
+
+```html
+<script>
+	import { tweened } from 'svelte/motion';
+
+	const progress = tweened(0);
+</script>
+```
+
+Clicking the buttons causes the progress bar to animate to its new value. It's a bit robotic and unsatisfying though. We need to add an easing function:
+
+```html
+<script>
+	import { tweened } from 'svelte/motion';
+	import { cubicOut } from 'svelte/easing';
+
+	const progress = tweened(0, {
+		duration: 400,
+		easing: cubicOut
+	});
+</script>
+```
+
+> The `svelte/easing` module contains the [Penner easing equations](http://robertpenner.com/easing/), or you can supply your own `t => u` function where `t` and `u` are both values between 0 and 1.
+
+The full set of options available to `tweened`:
+
+* `delay` — milliseconds before the tween starts
+* `duration` — either the duration of the tween in milliseconds, or a `(from, to) => milliseconds` function allowing you to (e.g.) specify longer tweens for larger changes in value
+* `easing` — a `t => u` function
+* `interpolate` — a custom `(from, to) => u => value` function for interpolating between arbitrary values. By default, Svelte will interpolate between numbers, dates, and identically-shaped arrays and objects (as long as they only contain numbers and dates or other valid arrays and objects). If you want to interpolate (for example) colour strings or transformation matrices, supply a custom interpolator
+
+You can also pass these options to `progress.set` and `progress.update` as a second argument, in which case they will override the defaults. The `set` and `update` methods both return a promise that resolves when the tween completes.
\ No newline at end of file
diff --git a/site/content/tutorial/08-motion/02-spring/app-a/App.svelte b/site/content/tutorial/08-motion/02-spring/app-a/App.svelte
new file mode 100644
index 0000000000..813c6366b1
--- /dev/null
+++ b/site/content/tutorial/08-motion/02-spring/app-a/App.svelte
@@ -0,0 +1,31 @@
+<script>
+	import { writable } from 'svelte/store';
+
+	let coords = writable({ x: 50, y: 50 });
+	let size = writable(10);
+</script>
+
+<style>
+	svg { width: 100%; height: 100%; margin: -8px; }
+	circle { fill: #ff3e00 }
+</style>
+
+<div style="position: absolute; right: 1em;">
+	<label>
+		<h3>stiffness ({coords.stiffness})</h3>
+		<input bind:value={coords.stiffness} type="range" min="0" max="1" step="0.01">
+	</label>
+
+	<label>
+		<h3>damping ({coords.damping})</h3>
+		<input bind:value={coords.damping} type="range" min="0" max="1" step="0.01">
+	</label>
+</div>
+
+<svg
+	on:mousemove="{e => coords.set({ x: e.clientX, y: e.clientY })}"
+	on:mousedown="{() => size.set(30)}"
+	on:mouseup="{() => size.set(10)}"
+>
+	<circle cx={$coords.x} cy={$coords.y} r={$size}/>
+</svg>
\ No newline at end of file
diff --git a/site/content/tutorial/08-motion/02-spring/app-b/App.svelte b/site/content/tutorial/08-motion/02-spring/app-b/App.svelte
new file mode 100644
index 0000000000..2cb0fd1eb7
--- /dev/null
+++ b/site/content/tutorial/08-motion/02-spring/app-b/App.svelte
@@ -0,0 +1,35 @@
+<script>
+	import { spring } from 'svelte/motion';
+
+	let coords = spring({ x: 50, y: 50 }, {
+		stiffness: 0.1,
+		damping: 0.25
+	});
+
+	let size = spring(10);
+</script>
+
+<style>
+	svg { width: 100%; height: 100% }
+	circle { fill: #ff3e00 }
+</style>
+
+<div style="position: absolute; right: 1em;">
+	<label>
+		<h3>stiffness ({coords.stiffness})</h3>
+		<input bind:value={coords.stiffness} type="range" min="0" max="1" step="0.01">
+	</label>
+
+	<label>
+		<h3>damping ({coords.damping})</h3>
+		<input bind:value={coords.damping} type="range" min="0" max="1" step="0.01">
+	</label>
+</div>
+
+<svg
+	on:mousemove="{e => coords.set({ x: e.clientX, y: e.clientY })}"
+	on:mousedown="{() => size.set(30)}"
+	on:mouseup="{() => size.set(10)}"
+>
+	<circle cx={$coords.x} cy={$coords.y} r={$size}/>
+</svg>
\ No newline at end of file
diff --git a/site/content/tutorial/08-motion/02-spring/text.md b/site/content/tutorial/08-motion/02-spring/text.md
new file mode 100644
index 0000000000..6d99e1b8c4
--- /dev/null
+++ b/site/content/tutorial/08-motion/02-spring/text.md
@@ -0,0 +1,27 @@
+---
+title: Spring
+---
+
+The `spring` function is an alternative to `tweened` that often works better for values that are frequently changing.
+
+In this example we have two stores — one representing the circle's coordinates, and one representing its size. Let's convert them to springs:
+
+```html
+<script>
+	import { spring } from 'svelte/motion';
+
+	let coords = spring({ x: 50, y: 50 });
+	let size = spring(10);
+</script>
+```
+
+Both springs have default `stiffness` and `damping` values, which control the spring's, well... springiness. We can specify our own initial values:
+
+```js
+let coords = spring({ x: 50, y: 50 }, {
+	stiffness: 0.1,
+	damping: 0.25
+});
+```
+
+Waggle your mouse around, and try dragging the sliders to get a feel for how they affect the spring's behaviour. Notice that you can adjust the values while the spring is still in motion.
\ No newline at end of file
diff --git a/site/content/tutorial/08-motion/meta.json b/site/content/tutorial/08-motion/meta.json
new file mode 100644
index 0000000000..e6fa83cd7f
--- /dev/null
+++ b/site/content/tutorial/08-motion/meta.json
@@ -0,0 +1,3 @@
+{
+	"title": "Motion"
+}
\ No newline at end of file
diff --git a/site/content/tutorial/99-todo/99-todo/text.md b/site/content/tutorial/99-todo/99-todo/text.md
index 15d6327819..743f5ab75f 100644
--- a/site/content/tutorial/99-todo/99-todo/text.md
+++ b/site/content/tutorial/99-todo/99-todo/text.md
@@ -89,8 +89,8 @@ Maybe lifecycle should go first, since we're using `onMount` in the `this` demo?
 
 ## Motion
 
-* [ ] `tweened`
-* [ ] `spring`
+* [x] `tweened`
+* [x] `spring`
 
 
 ## Lifecycle