docs: updates (#60)

package.json

@@ -7,7 +7,7 @@
 	"main": "index.js",
 	"scripts": {
 		"test": "pnpm -r test",
-		"dev": "pnpm -F \"./packages/**\" --parallel dev",
+		"dev": "pnpm -r --parallel dev",
 		"build": "pnpm -r build",
 		"build:packages": "pnpm -F \"./packages/**\" --parallel build",
 		"ci:publish": "pnpm build:packages && changeset publish",

packages/mode-watcher/.eslintrc.cjs

@@ -25,6 +25,15 @@ module.exports = {
 			parserOptions: {
 				parser: '@typescript-eslint/parser',
 			},
+			rules: {
+				'@typescript-eslint/no-unused-vars': [
+					'warn',
+					{
+						argsIgnorePattern: '^_',
+						varsIgnorePattern: '^\\$\\$(Props|Events|Slots|Generic)$',
+					},
+				],
+			},
 		},
 	],
 };

packages/mode-watcher/package.json

@@ -9,16 +9,17 @@
 		"directory": "packages/mode-watcher"
 	},
 	"scripts": {
-		"dev": "vite dev",
-		"build": "vite build && pnpm run package",
+		"dev": "pnpm watch",
+		"build": "pnpm run package",
 		"preview": "vite preview",
 		"package": "svelte-kit sync && svelte-package && publint",
 		"prepublishOnly": "pnpm run package",
 		"test": "vitest",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"lint": "prettier --plugin-search-dir . --check . && eslint .",
-		"format": "prettier --plugin-search-dir . --write ."
+		"format": "prettier --plugin-search-dir . --write .",
+		"watch": "svelte-kit sync && svelte-package --watch"
 	},
 	"exports": {
 		".": {

packages/mode-watcher/src/lib/mode-watcher.svelte

@@ -8,9 +8,11 @@
 		themeColors as themeColorsStore,
 		setInitialMode,
 	} from './mode.js';
-	import type { Mode, ThemeColors } from './types.js';
+	import type { Mode, ModeWatcherProps, ThemeColors } from './types.js';
 	import { isValidMode } from './stores.js';
 
+	type $$Props = ModeWatcherProps;
+
 	export let track = true;
 	export let defaultMode: Mode = 'system';
 	export let themeColors: ThemeColors = undefined;

packages/mode-watcher/src/lib/types.ts

@@ -2,3 +2,25 @@ import type { modes } from './stores';
 
 export type Mode = (typeof modes)[number];
 export type ThemeColors = { dark: string; light: string } | undefined;
+
+export type ModeWatcherProps = {
+	/**
+	 * Whether to automatically track operating system preferences
+	 * and update the mode accordingly.
+	 *
+	 * @defaultValue `true`
+	 */
+	track?: boolean;
+
+	/**
+	 * The default mode to use instead of the user's preference.
+	 *
+	 * @defaultValue `"system"`
+	 */
+	defaultMode?: Mode;
+
+	/**
+	 * The theme colors to use for each mode.
+	 */
+	themeColors?: ThemeColors;
+};

sites/docs/content/api-reference/local-storage-key.md

@@ -0,0 +1,28 @@
+---
+title: localStorageKey
+description: The key used to store the mode in local storage.
+tagline: API Reference
+---
+
+<script>
+	import { Callout } from '$lib/components'
+</script>
+
+The key used to store the mode in local storage.
+
+## Usage
+
+If you wanted to clear the history of the user's mode preference, you could use the `localStorageKey` like so:
+
+```svelte
+<script lang="ts">
+	import { localStorageKey } from "mode-watcher";
+
+	function clearModeFromLocalStorage() {
+		localStorage.removeItem(localStorageKey);
+	}
+</script>
+
+<p>Clear the user's mode preference history.</p>
+<button on:click={clearModeFromLocalStorage}>Clear</button>
+```

sites/docs/content/api-reference/mode-watcher.md

@@ -8,8 +8,78 @@ tagline: API Reference
 	import { Callout } from '$lib/components'
 </script>
 
-<Callout type="warning">
+## Usage
 
-The documentation is still a work in progress. Please refer to the [GitHub README](https://github.com/svecosystem/mode-watcher) for more information.
+Add the `ModeWatcher` component to your root `+layout.svelte` component.
 
-</Callout>
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+	import { ModeWatcher } from "mode-watcher";
+</script>
+
+<ModeWatcher />
+<slot />
+```
+
+The `ModeWatcher` component will automatically detect the user's preferences and apply/remove the "dark" class, along with the corresponding color-scheme style attribute to the html element.
+
+### Disable Tracking
+
+`ModeWatcher` will automatically track operating system preferences and apply these if no user preference is set. If you wish to disable this behavior, set the track prop to false:
+
+```svelte
+<ModeWatcher track={false} />
+```
+
+### Default Mode
+
+`ModeWatcher` can be configured with a default mode instead of automatically detecting the user's preference.
+
+To set a default mode, use the `defaultMode` prop:
+
+```svelte
+<ModeWatcher defaultMode="dark" />
+```
+
+### Theme Colors
+
+`ModeWatcher` can manage the theme-color meta tag for you.
+
+To enable this, set the `themeColors` prop to your preferred colors:
+
+```svelte
+<ModeWatcher themeColors={{ dark: "#000", light: "#fff" }} />
+```
+
+## Props
+
+The `ModeWatcher` component accepts the following props:
+
+```ts
+export type Mode = "system" | "dark" | "light";
+export type ThemeColors = { dark: string; light: string };
+
+export type ModeWatcherProps = {
+	/**
+	 * Whether to automatically track operating system preferences
+	 * and update the mode accordingly.
+	 *
+	 * @defaultValue `true`
+	 */
+	track?: boolean;
+
+	/**
+	 * The default mode to use instead of the user's preference.
+	 *
+	 * @defaultValue `"system"`
+	 */
+	defaultMode?: Mode;
+
+	/**
+	 * The theme colors to use for each mode.
+	 *
+	 * @defaultValue `undefined`
+	 */
+	themeColors?: ThemeColors;
+};
+```

sites/docs/content/api-reference/mode.md

@@ -0,0 +1,25 @@
+---
+title: mode
+description: A store for tracking the current mode.
+tagline: API Reference
+---
+
+A readable store that contains the current mode. It can be `"light"` or `"dark"`, or if evaluated on the server, `undefined`.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { setMode, mode } from "mode-watcher";
+
+	function handleModeChange() {
+		if ($mode === "light") {
+			setMode("dark");
+		} else {
+			setMode("light");
+		}
+	}
+</script>
+
+<button on:click={handleModeChange}>{$mode}</button>
+```

sites/docs/content/api-reference/reset-mode.md

@@ -0,0 +1,17 @@
+---
+title: resetMode
+description: Programatically reset the mode to system preference.
+tagline: API Reference
+---
+
+A function that resets the mode to system preferences.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { resetMode } from "mode-watcher";
+</script>
+
+<button on:click={resetMode}>System</button>
+```

sites/docs/content/api-reference/set-mode.md

@@ -0,0 +1,18 @@
+---
+title: setMode
+description: Programatically set the mode.
+tagline: API Reference
+---
+
+A function that sets the current mode. It accepts a string with the value `"light"`, `"dark"` or `"system"`.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { setMode } from "mode-watcher";
+</script>
+
+<button on:click={() => setMode("light")}>Set Light Mode</button>
+<button on:click={() => setMode("dark")}>Set Dark Mode</button>
+```

sites/docs/content/api-reference/system-prefers-mode.md

@@ -0,0 +1,19 @@
+---
+title: systemPrefersMode
+description: A store for tracking the system's preferred mode.
+tagline: API Reference
+---
+
+A readable store that represents the operating system's mode preference. It can be `"light"` or `"dark"`, or if evaluated on the server, `undefined`.
+
+This store will automatically track changes to the operating system's mode preference unless this is disabled by setting the `track` prop to `false` in the [ModeWatcher](/docs/api-reference/mode-watcher) component.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { systemPrefersMode } from "mode-watcher";
+</script>
+
+<p>The system prefers mode is: {$systemPrefersMode}</p>
+```

sites/docs/content/api-reference/toggle-mode.md

@@ -0,0 +1,17 @@
+---
+title: toggleMode
+description: Programatically toggle the mode.
+tagline: API Reference
+---
+
+A function that can be used to programatically toggle the mode.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { toggleMode } from "mode-watcher";
+</script>
+
+<button on:click={toggleMode}>Toggle Mode</button>
+```

sites/docs/content/api-reference/user-prefers-mode.md

@@ -0,0 +1,17 @@
+---
+title: userPrefersMode
+description: A store for tracking the user's preferred mode.
+tagline: API Reference
+---
+
+A writeable store that represents the user's mode preference. It can be "light", "dark" or "system".
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { userPrefersMode } from "mode-watcher";
+</script>
+
+<p>Your preferred mode is: {$userPrefersMode}</p>
+```

sites/docs/package.json

@@ -45,7 +45,7 @@
 		"eslint-config-prettier": "^9.1.0",
 		"eslint-plugin-svelte": "^2.35.1",
 		"hast-util-to-html": "^9.0.0",
-		"mdsx": "^0.0.3",
+		"mdsx": "^0.0.5",
 		"phosphor-svelte": "^1.4.2",
 		"postcss": "^8.4.32",
 		"postcss-load-config": "^5.0.2",

sites/docs/src/lib/components/layout/navbar/navbar-logo.svelte

@@ -7,8 +7,8 @@
 		href="/"
 		class="flex flex-shrink-0 items-end gap-1.5 text-xl font-bold text-gray-900 dark:text-white"
 	>
-		<ModeWatcherLight class="block h-[26px] w-auto dark:hidden" />
-		<ModeWatcherDark class="hidden h-[26px] w-auto dark:block" />
+		<ModeWatcherLight class="block h-7 w-auto dark:hidden" />
+		<ModeWatcherDark class="hidden h-7 w-auto dark:block" />
 		<span class="sr-only"> Home </span>
 	</a>
 </div>