From 7a292bc514ab021ac33a3f2fd3fea68a1db44083 Mon Sep 17 00:00:00 2001
From: Hunter Johnston <64506580+huntabyte@users.noreply.github.com>
Date: Fri, 26 Apr 2024 20:31:38 -0400
Subject: [PATCH] docs: cleanup (#27)

Co-authored-by: AdrianGonz97 <31664583+AdrianGonz97@users.noreply.github.com>
---
 sites/docs/content/functions/box.md           | 28 +++---
 .../content/functions/use-active-element.md   |  1 +
 sites/docs/content/functions/use-debounce.md  |  1 +
 .../content/functions/use-element-size.md     |  1 +
 .../content/functions/use-event-listener.md   |  1 +
 sites/docs/content/functions/use-mounted.md   |  1 +
 sites/docs/content/functions/use-supported.md |  1 +
 sites/docs/content/getting-started.md         |  8 --
 sites/docs/content/index.md                   | 22 +----
 sites/docs/contentlayer.config.js             | 24 ++++-
 sites/docs/src/lib/config/navigation.ts       | 94 ++++++++++---------
 11 files changed, 98 insertions(+), 84 deletions(-)

diff --git a/sites/docs/content/functions/box.md b/sites/docs/content/functions/box.md
index ac70b896..ff61b8a2 100644
--- a/sites/docs/content/functions/box.md
+++ b/sites/docs/content/functions/box.md
@@ -1,6 +1,7 @@
 ---
 title: Box
 description: Box your state and take it anywhere
+category: State
 ---
 
 <script>
@@ -9,23 +10,23 @@ import { UseActiveElementDemo } from '$lib/components/demos';
 
 ## Description
 
-State in runes is based on primitives, which provides a concise syntax. However, when sending these
-primitives across boundaries, e.g. in function arguments, the state is not reactive, and rather, the
-static value gets sent.
+Runes for state are primitives. They provide a concise syntax for local reactivity. However, when we
+send these state primitives across boundaries (e.g. in function arguments), the state loses it's
+reactivity and becomes a static value.
 
-Box provides several utilities to make sending and receiving reactive values easier.
+Boxes provide several utilities to make passing reactive state across boundaries easier.
 
 ## Usage
 
 ### `box`
 
-Initializes the boxed state.
+Initializes a writable boxed state.
 
 ```svelte
 <script lang="ts">
 	import { box } from "runed";
 
-	let count = box(0);
+	const count = box(0);
 </script>
 
 <button onclick={() => count.value++}>
@@ -35,7 +36,10 @@ Initializes the boxed state.
 
 ### `box.with`
 
-Allows you to use getters and setters to define a box. Useful to pass around state.
+Creates reactive state using getter and setter functions. If a setter function is provided, the box
+is writable. If not, the box is readonly.
+
+Useful for passing synced reactive values across boundaries.
 
 ```svelte
 <script lang="ts">
@@ -52,7 +56,7 @@ Allows you to use getters and setters to define a box. Useful to pass around sta
 	}
 
 	let count = $state(0);
-	// We pass count with box.with
+	// We pass count to box.with so it stays in sync
 	const { double, increment } = useCounter(
 		box.with(
 			() => count.value,
@@ -69,8 +73,9 @@ Allows you to use getters and setters to define a box. Useful to pass around sta
 
 ### `box.from`
 
-Creates a box from an existing box, a getter function, or a static value. Used in functions to
-receive props that are optionally reactive.
+Creates a box from an existing box, a getter function, or a static value.
+
+Useful for receiving arguments that may or may not be reactive.
 
 ```svelte
 <script lang="ts">
@@ -116,7 +121,8 @@ receive props that are optionally reactive.
 
 ### `box.flatten`
 
-Transforms any boxes inside an object to reactive properties, flattening the `.value` onto them.
+Transforms any boxes within an object to reactive properties, removing the need to access each
+property with `.value`.
 
 ```ts
 const count = box(1);
diff --git a/sites/docs/content/functions/use-active-element.md b/sites/docs/content/functions/use-active-element.md
index 9970278c..f245b82a 100644
--- a/sites/docs/content/functions/use-active-element.md
+++ b/sites/docs/content/functions/use-active-element.md
@@ -1,6 +1,7 @@
 ---
 title: useActiveElement
 description: A function that returns the currently active element.
+category: Elements
 ---
 
 <script>
diff --git a/sites/docs/content/functions/use-debounce.md b/sites/docs/content/functions/use-debounce.md
index 9fb19547..4a404334 100644
--- a/sites/docs/content/functions/use-debounce.md
+++ b/sites/docs/content/functions/use-debounce.md
@@ -1,6 +1,7 @@
 ---
 title: useDebounce
 description: A higher-order function that debounces the execution of a function.
+category: Utilities
 ---
 
 <script>
diff --git a/sites/docs/content/functions/use-element-size.md b/sites/docs/content/functions/use-element-size.md
index 095972e2..ca212916 100644
--- a/sites/docs/content/functions/use-element-size.md
+++ b/sites/docs/content/functions/use-element-size.md
@@ -1,6 +1,7 @@
 ---
 title: useElementSize
 description: A higher-order function that debounces the execution of a function.
+category: Elements
 ---
 
 <script>
diff --git a/sites/docs/content/functions/use-event-listener.md b/sites/docs/content/functions/use-event-listener.md
index 87750006..7320b893 100644
--- a/sites/docs/content/functions/use-event-listener.md
+++ b/sites/docs/content/functions/use-event-listener.md
@@ -1,6 +1,7 @@
 ---
 title: useEventListener
 description: A function that attaches an automatically disposed event listener.
+category: Browser
 ---
 
 <script>
diff --git a/sites/docs/content/functions/use-mounted.md b/sites/docs/content/functions/use-mounted.md
index 44777133..eec32c62 100644
--- a/sites/docs/content/functions/use-mounted.md
+++ b/sites/docs/content/functions/use-mounted.md
@@ -1,6 +1,7 @@
 ---
 title: useMounted
 description: A function that returns the mounted state of the component it's called in.
+category: Component
 ---
 
 <script>
diff --git a/sites/docs/content/functions/use-supported.md b/sites/docs/content/functions/use-supported.md
index a12c2eba..8975cf13 100644
--- a/sites/docs/content/functions/use-supported.md
+++ b/sites/docs/content/functions/use-supported.md
@@ -1,6 +1,7 @@
 ---
 title: useSupported
 description: Determine if a feature is supported by the environment before using it.
+category: Utilities
 ---
 
 ## Usage
diff --git a/sites/docs/content/getting-started.md b/sites/docs/content/getting-started.md
index 2eedfc37..4d6c664c 100644
--- a/sites/docs/content/getting-started.md
+++ b/sites/docs/content/getting-started.md
@@ -10,11 +10,3 @@ Install Runed using your favorite package manager:
 ```bash
 npm install runed
 ```
-
-## Basic Usage
-
-Here's a simple example of how to use Runed
-
-```svelte
-<!-- TODO -->
-```
diff --git a/sites/docs/content/index.md b/sites/docs/content/index.md
index de32a085..47c10fc4 100644
--- a/sites/docs/content/index.md
+++ b/sites/docs/content/index.md
@@ -1,23 +1,7 @@
 ---
 title: Introduction
-description: What this project is all about.
+description: Runes are magic, but what good is magic if you don't have a wand?
 ---
 
-<script>
-</script>
-
-Runed provides utilities to power your applications using the magic of
-[Svelte Runes](https://svelte.dev/blog/runes).
-
-Here are some tools that are provided:
-
-- Debouncing utilities synced with state
-- Element size tracking
-- RequestAnimationFrame helpers
-- etc.
-
-## Next Steps
-
-Start using Runed in your Svelte app by following the [Getting Started](/docs/getting-started)
-guide. If you have any questions or need help, feel free to ask in the
-[Discord](https://discord.gg/hbAGu6akVy)!
+Runed is a collection of utilities for Svelte 5 that make composing powerful applications and
+libraries a breeze, leveraging the power of [Svelte Runes](https://svelte.dev/blog/runes).
diff --git a/sites/docs/contentlayer.config.js b/sites/docs/contentlayer.config.js
index 2f79f476..51df5516 100644
--- a/sites/docs/contentlayer.config.js
+++ b/sites/docs/contentlayer.config.js
@@ -23,7 +23,7 @@ const computedFields = {
 
 export const Doc = defineDocumentType(() => ({
 	name: "Doc",
-	filePathPattern: `**/*.md`,
+	filePathPattern: `./*.md`,
 	fields: {
 		title: {
 			type: "string",
@@ -41,8 +41,28 @@ export const Doc = defineDocumentType(() => ({
 	computedFields,
 }));
 
+export const FunctionDoc = defineDocumentType(() => ({
+	name: "FunctionDoc",
+	filePathPattern: "functions/**/*.md",
+	fields: {
+		title: {
+			type: "string",
+			required: true,
+		},
+		description: {
+			type: "string",
+			required: true,
+		},
+		category: {
+			type: "string",
+			required: true,
+		},
+	},
+	computedFields,
+}));
+
 export default makeSource({
 	contentDirPath: "./content",
-	documentTypes: [Doc],
+	documentTypes: [Doc, FunctionDoc],
 	disableImportAliasWarning: true,
 });
diff --git a/sites/docs/src/lib/config/navigation.ts b/sites/docs/src/lib/config/navigation.ts
index 4a94194b..fc0cb167 100644
--- a/sites/docs/src/lib/config/navigation.ts
+++ b/sites/docs/src/lib/config/navigation.ts
@@ -1,3 +1,5 @@
+import { allFunctionDocs } from "../../../.contentlayer/generated";
+
 export type NavItem = {
 	title: string;
 	href?: string;
@@ -20,8 +22,54 @@ export type Navigation = {
 	sidebar: SidebarNavItem[];
 };
 
+const CATEGORIES = ["State", "Elements", "Browser", "Component", "Utilities"] as const;
+type Category = (typeof CATEGORIES)[number];
+
+function isCategory(category: string): category is Category {
+	return CATEGORIES.includes(category as Category);
+}
+
+function generateFunctionsNav() {
+	const categories = new Set(
+		allFunctionDocs
+			.map((doc) => doc.category)
+			.filter((category): category is Category => isCategory(category))
+	);
+
+	const navItems: SidebarNavItem[] = [];
+
+	// Create a map to store the items for each category
+	const categoryItemsMap: Record<string, SidebarNavItem["items"]> = {};
+
+	// Populate the map with items for each category
+	for (const doc of allFunctionDocs) {
+		if (!categoryItemsMap[doc.category]) {
+			categoryItemsMap[doc.category] = [];
+		}
+		categoryItemsMap[doc.category]?.push({
+			title: doc.title,
+			href: `/docs/functions/${doc.slug}`,
+			items: [],
+		});
+	}
+
+	// Sort the categories based on the provided sort order
+	const sortedCategories = CATEGORIES.filter((category) => categories.has(category));
+
+	// Create the navItems array based on the sorted categories
+	for (const category of sortedCategories) {
+		const items = categoryItemsMap[category] ?? [];
+		navItems.push({
+			title: category,
+			items,
+			collapsible: false,
+		});
+	}
+
+	return navItems;
+}
+
 export const navigation: Navigation = {
-	// By default, `main` navigation items are rendered in the top navigation bar.
 	main: [
 		{
 			title: "Documentation",
@@ -38,7 +86,6 @@ export const navigation: Navigation = {
 			external: true,
 		},
 	],
-	// By default, `sidebar` navigation only supports 2 levels of navigation.
 	sidebar: [
 		{
 			title: "Overview",
@@ -56,47 +103,6 @@ export const navigation: Navigation = {
 				},
 			],
 		},
-
-		{
-			title: "Functions",
-			collapsible: true,
-			items: [
-				{
-					title: "Box",
-					href: "/docs/functions/box",
-					items: [],
-				},
-				{
-					title: "useActiveElement",
-					href: "/docs/functions/use-active-element",
-					items: [],
-				},
-				{
-					title: "useDebounce",
-					href: "/docs/functions/use-debounce",
-					items: [],
-				},
-				{
-					title: "useElementSize",
-					href: "/docs/functions/use-element-size",
-					items: [],
-				},
-				{
-					title: "useEventListener",
-					href: "/docs/functions/use-event-listener",
-					items: [],
-				},
-				{
-					title: "useMounted",
-					href: "/docs/functions/use-mounted",
-					items: [],
-				},
-				{
-					title: "useSupported",
-					href: "/docs/functions/use-supported",
-					items: [],
-				},
-			],
-		},
+		...generateFunctionsNav(),
 	],
 };