add toast/flash docs

Author: kentcdodds

app/root.tsx

@@ -118,7 +118,7 @@ export async function loader({ request }: DataFunctionArgs) {
 		},
 		{
 			headers: combineHeaders(
-				new Headers({ 'Server-Timing': timings.toString() }),
+				{ 'Server-Timing': timings.toString() },
 				flasHeaders,
 			),
 		},

app/utils/flash-session.server.ts

@@ -35,6 +35,22 @@ function getSessionFromRequest(request: Request) {
 
 	return sessionStorage.getSession(cookie)
 }
+
+/**
+ * Helper method used to add flash session values to the session
+ */
+export async function flashMessage(
+	flash: FlashSessionValues,
+	headers?: ResponseInit['headers'],
+) {
+	const session = await sessionStorage.getSession()
+	session.flash(FLASH_SESSION, flash)
+	const cookie = await sessionStorage.commitSession(session)
+	const newHeaders = new Headers(headers)
+	newHeaders.append('Set-Cookie', cookie)
+	return newHeaders
+}
+
 /**
  * Helper method used to redirect the user to a new page with flash session values
  * @param url Url to redirect to
@@ -47,16 +63,9 @@ export async function redirectWithFlash(
 	flash: FlashSessionValues,
 	init?: ResponseInit,
 ) {
-	const session = await sessionStorage.getSession()
-	session.flash(FLASH_SESSION, flash)
-	const headers = new Headers(init?.headers)
-	const flashCookie = await sessionStorage.commitSession(session)
-	// We append the flash cookie to the session
-	headers.append('Set-Cookie', flashCookie)
-
 	return redirect(url, {
 		...init,
-		headers,
+		headers: await flashMessage(flash, init?.headers),
 	})
 }
 /**

app/utils/misc.ts

@@ -36,10 +36,10 @@ export function getDomainUrl(request: Request) {
 /**
  * Merge multiple headers objects into one (uses set so headers are overridden)
  */
-export function mergeHeaders(...headers: Array<Headers>) {
+export function mergeHeaders(...headers: Array<ResponseInit['headers']>) {
 	const merged = new Headers()
 	for (const header of headers) {
-		for (const [key, value] of header.entries()) {
+		for (const [key, value] of new Headers(header).entries()) {
 			merged.set(key, value)
 		}
 	}
@@ -49,10 +49,10 @@ export function mergeHeaders(...headers: Array<Headers>) {
 /**
  * Combine multiple header objects into one (uses append so headers are not overridden)
  */
-export function combineHeaders(...headers: Array<Headers>) {
+export function combineHeaders(...headers: Array<ResponseInit['headers']>) {
 	const combined = new Headers()
 	for (const header of headers) {
-		for (const [key, value] of header.entries()) {
+		for (const [key, value] of new Headers(header).entries()) {
 			combined.append(key, value)
 		}
 	}

docs/toasts.md

@@ -0,0 +1,64 @@
+# Toasts
+
+Toast messages are great ways to temporarily call someone's attention to
+something. They are often used to notify users of a successful or failed action.
+
+![confetti](https://github.com/epicweb-dev/epic-stack/assets/1500684/6183b362-5682-4ab0-aa1a-7cc1e4f72f9e)
+
+![toasts](https://github.com/epicweb-dev/epic-stack/assets/1500684/715d754a-9e9f-4b61-814f-881121f2fa48)
+
+There are utilities in the Epic Stack for toast notifications. Additionally, the
+same code used to power a toast notification is also used to power the Confetti
+component which is used to celebrate when a user signs up for an account (feel
+free to remove that or use it for other things as well).
+
+This is managed by a special session using a concept called "flash data" which
+is a temporary session value that is only available for the next request. This
+is a great way to pass data to the next request without having to worry about
+the data persisting in the session. And you don't have to worry about managing
+state either. It all just lives in the cookie.
+
+There are two utilities you'll use for redirecting with toast/confetti
+notifications from the `app/utils/flash-session.server.ts` file:
+`redirectWithToast` and `redirectWithConfetti`. Here's a simple example of using
+these:
+
+```tsx
+return redirectWithToast(`/users/${note.owner.username}/notes/${note.id}`, {
+	title: id ? 'Note updated' : 'Note created',
+})
+// or
+return redirectWithConfetti(safeRedirect(redirectTo, '/'))
+```
+
+Each of these accepts an additional argument for other `ResponseInit` options so
+you can set other headers, etc.
+
+If you don't wish to redirect, you could use the underlying `flashMessage`
+directly:
+
+```tsx
+return json(
+	{ success: true },
+	{
+		headers: await flashMessage({
+			toast: {
+				title: 'Note updated',
+				type: 'success',
+			},
+		}),
+	},
+)
+```
+
+And if you need to set multiple headers, you can pass them as a second argument
+to `flashMessage`:
+
+```tsx
+flashMessage(
+	{
+		/* ... */
+	},
+	{ 'X-My-Header': 'My value' },
+)
+```