From d47bd2c65d37279d10b76e09e562c471cd3ee0e3 Mon Sep 17 00:00:00 2001
From: Simon Holthausen <simon.holthausen@vercel.com>
Date: Tue, 28 Mar 2023 14:17:59 +0200
Subject: [PATCH] fix: component docs, fix some type issues

---
 .changeset/gold-days-teach.md                 |  5 ++++
 packages/site-kit/package.json                |  1 +
 .../site-kit/src/lib/components/Icon.svelte   | 12 ++++-----
 .../site-kit/src/lib/components/Icons.svelte  |  3 +++
 .../site-kit/src/lib/components/Nav.svelte    |  5 ++++
 .../src/lib/components/NavItem.svelte         |  4 +++
 .../src/lib/components/Separator.svelte       |  3 +++
 .../site-kit/src/lib/components/Shell.svelte  |  9 +++++++
 .../src/lib/components/SkipLink.svelte        |  4 +++
 .../site-kit/src/lib/search/Search.svelte     |  7 +++--
 .../site-kit/src/lib/search/SearchBox.svelte  | 14 ++++++++--
 .../src/lib/search/SearchResults.svelte       |  3 +++
 packages/site-kit/src/lib/search/search.js    | 27 ++++++++++++-------
 pnpm-lock.yaml                                |  7 ++++-
 14 files changed, 84 insertions(+), 20 deletions(-)
 create mode 100644 .changeset/gold-days-teach.md

diff --git a/.changeset/gold-days-teach.md b/.changeset/gold-days-teach.md
new file mode 100644
index 00000000..a30f1a2b
--- /dev/null
+++ b/.changeset/gold-days-teach.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/site-kit': patch
+---
+
+fix: component docs, fix some type issues
diff --git a/packages/site-kit/package.json b/packages/site-kit/package.json
index c96e0ed6..6b6e6f65 100644
--- a/packages/site-kit/package.json
+++ b/packages/site-kit/package.json
@@ -22,6 +22,7 @@
 	"devDependencies": {
 		"@sveltejs/kit": "^1.3.10",
 		"@sveltejs/package": "^1.0.2",
+		"flexsearch": "^0.7.31",
 		"svelte": "^3.55.1",
 		"typescript": "^4.9.5",
 		"vite": "^4.0.4"
diff --git a/packages/site-kit/src/lib/components/Icon.svelte b/packages/site-kit/src/lib/components/Icon.svelte
index c4ee3fe1..2bb4c9e5 100644
--- a/packages/site-kit/src/lib/components/Icon.svelte
+++ b/packages/site-kit/src/lib/components/Icon.svelte
@@ -1,12 +1,12 @@
-<!--
------------------------------------------------
-	svg icon
-	- https://github.com/jacobmischka/svelte-feather-icon
-	- https://feathericons.com/
------------------------------------------------
+<!--@component
+use an svg icon that was provided through `Icons.svelte` from
+- https://github.com/jacobmischka/svelte-feather-icon
+- https://feathericons.com/
 -->
 <script>
+	/** @type {string} */
 	export let name;
+	/** @type {string | number} */
 	export let size = 20;
 </script>
 
diff --git a/packages/site-kit/src/lib/components/Icons.svelte b/packages/site-kit/src/lib/components/Icons.svelte
index f0f7d95b..268503a4 100644
--- a/packages/site-kit/src/lib/components/Icons.svelte
+++ b/packages/site-kit/src/lib/components/Icons.svelte
@@ -1,3 +1,6 @@
+<!--@component
+Provides a list of svg icons that can be referenced through the `Icon` component
+-->
 <div style="display: none">
 	<!-- wrapper div allows use of innerHTML -->
 	<svg>
diff --git a/packages/site-kit/src/lib/components/Nav.svelte b/packages/site-kit/src/lib/components/Nav.svelte
index ebbd9c82..d912c4c7 100644
--- a/packages/site-kit/src/lib/components/Nav.svelte
+++ b/packages/site-kit/src/lib/components/Nav.svelte
@@ -1,13 +1,18 @@
+<!-- @component
+Top navigation bar for the application. It provides a slot for the left side, the right side, and the center.
+-->
 <script>
 	import { page } from '$app/stores';
 	import Icon from './Icon.svelte';
 
+	/** @type {string} */
 	export let logo;
 	export let home = 'Home';
 	export let home_title = 'Homepage';
 
 	let open = false;
 	let visible = true;
+	/** @type {HTMLElement} */
 	let nav;
 
 	// hide nav whenever we navigate
diff --git a/packages/site-kit/src/lib/components/NavItem.svelte b/packages/site-kit/src/lib/components/NavItem.svelte
index c4ec4dd0..2d76da5e 100644
--- a/packages/site-kit/src/lib/components/NavItem.svelte
+++ b/packages/site-kit/src/lib/components/NavItem.svelte
@@ -1,3 +1,6 @@
+<!-- @component
+Simple item component for use within `Nav`
+-->
 <script>
 	/** @type {string | undefined} */
 	export let href = undefined;
@@ -8,6 +11,7 @@
 	/** @type {string | undefined} */
 	export let title = undefined;
 
+	/** @type {any}*/
 	export let selected = undefined;
 </script>
 
diff --git a/packages/site-kit/src/lib/components/Separator.svelte b/packages/site-kit/src/lib/components/Separator.svelte
index 179080fb..5baf9bf1 100644
--- a/packages/site-kit/src/lib/components/Separator.svelte
+++ b/packages/site-kit/src/lib/components/Separator.svelte
@@ -1,3 +1,6 @@
+<!-- @component
+Simple separator component for use within `Nav`
+-->
 <li aria-hidden="true"><span class="separator" /></li>
 
 <style>
diff --git a/packages/site-kit/src/lib/components/Shell.svelte b/packages/site-kit/src/lib/components/Shell.svelte
index b5232e06..a49bed4e 100644
--- a/packages/site-kit/src/lib/components/Shell.svelte
+++ b/packages/site-kit/src/lib/components/Shell.svelte
@@ -1,3 +1,6 @@
+<!-- @component
+The main shell of the application. It provides a slot for the top navigation, the main content, and the bottom banner.
+-->
 <script>
 	import { navigating } from '$app/stores';
 	import '../styles/index.css';
@@ -5,7 +8,13 @@
 	import PreloadingIndicator from './PreloadingIndicator.svelte';
 	import SkipLink from './SkipLink.svelte';
 
+	/**
+	 * Height of the bottom banner. If '0px', the banner is not visible.
+	 */
 	export let banner_bottom_height = '0px';
+	/**
+	 * Whether the navigation is visible.
+	 */
 	export let nav_visible = true;
 </script>
 
diff --git a/packages/site-kit/src/lib/components/SkipLink.svelte b/packages/site-kit/src/lib/components/SkipLink.svelte
index 2097d602..2b5170ca 100644
--- a/packages/site-kit/src/lib/components/SkipLink.svelte
+++ b/packages/site-kit/src/lib/components/SkipLink.svelte
@@ -1,4 +1,8 @@
+<!--@component
+Accessibility helper component to skip to the main content
+-->
 <script>
+	/** @type {string} */
 	export let href;
 </script>
 
diff --git a/packages/site-kit/src/lib/search/Search.svelte b/packages/site-kit/src/lib/search/Search.svelte
index c5feb5ef..fc81a920 100644
--- a/packages/site-kit/src/lib/search/Search.svelte
+++ b/packages/site-kit/src/lib/search/Search.svelte
@@ -1,3 +1,6 @@
+<!-- @component
+Renders a search widget which when clicked (or the corresponding keyboard shortcut is pressed) opens a search overlay.
+-->
 <script>
 	import { browser } from '$app/environment';
 	import { searching, query } from './stores.js';
@@ -10,8 +13,8 @@
 		value={q}
 		on:input={(e) => {
 			$searching = true;
-			$query = e.target.value;
-			e.target.value = '';
+			$query = e.currentTarget.value;
+			e.currentTarget.value = '';
 		}}
 		on:mousedown|preventDefault={() => ($searching = true)}
 		on:touchend|preventDefault={() => ($searching = true)}
diff --git a/packages/site-kit/src/lib/search/SearchBox.svelte b/packages/site-kit/src/lib/search/SearchBox.svelte
index 9ae20b7c..65102180 100644
--- a/packages/site-kit/src/lib/search/SearchBox.svelte
+++ b/packages/site-kit/src/lib/search/SearchBox.svelte
@@ -1,3 +1,7 @@
+<!-- @component
+Renders a search box as an overlay that can be used to search the documentation.
+It appears when the user clicks on the `Search` component or presses the corresponding keyboard shortcut.
+-->
 <script>
 	import { onMount } from 'svelte';
 	import Icon from '../components/Icon.svelte';
@@ -7,11 +11,15 @@
 	import SearchResults from './SearchResults.svelte';
 	import SearchWorker from './search-worker.js?worker';
 
+	/** @type {HTMLElement} */
 	let modal;
 
+	/** @type {any} */
 	let search = null;
+	/** @type {any[]} */
 	let recent_searches = [];
 
+	/** @type {Worker} */
 	let worker;
 	let ready = false;
 
@@ -137,11 +145,13 @@
 				autofocus
 				on:keydown={(e) => {
 					if (e.key === 'Enter') {
-						modal.querySelector('a[data-has-node]')?.click();
+						/** @type {HTMLElement | undefined} */ (
+							modal.querySelector('a[data-has-node]')
+						)?.click();
 					}
 				}}
 				on:input={(e) => {
-					$query = e.target.value;
+					$query = e.currentTarget.value;
 				}}
 				value={$query}
 				placeholder="Search"
diff --git a/packages/site-kit/src/lib/search/SearchResults.svelte b/packages/site-kit/src/lib/search/SearchResults.svelte
index 43b270e9..b09270d4 100644
--- a/packages/site-kit/src/lib/search/SearchResults.svelte
+++ b/packages/site-kit/src/lib/search/SearchResults.svelte
@@ -1,3 +1,6 @@
+<!--@component
+Renders a list of search results
+-->
 <script>
 	import SearchResultList from './SearchResultList.svelte';
 
diff --git a/packages/site-kit/src/lib/search/search.js b/packages/site-kit/src/lib/search/search.js
index d4a3f02e..cae97241 100644
--- a/packages/site-kit/src/lib/search/search.js
+++ b/packages/site-kit/src/lib/search/search.js
@@ -3,9 +3,10 @@ import flexsearch from 'flexsearch';
 // @ts-expect-error
 const Index = /** @type {import('flexsearch').Index} */ (flexsearch.Index) ?? flexsearch;
 
+/** If the search is already initialized */
 export let inited = false;
 
-/** @type {import('flexsearch').Index[]} */
+/** @type {import('flexsearch').Index<any>[]} */
 let indexes;
 
 /** @type {Map<string, import('./types').Block>} */
@@ -14,7 +15,10 @@ const map = new Map();
 /** @type {Map<string, string>} */
 const hrefs = new Map();
 
-/** @param {import('./types').Block[]} blocks */
+/**
+ * Initialize the search index
+ * @param {import('./types').Block[]} blocks
+ */
 export function init(blocks) {
 	if (inited) return;
 
@@ -43,8 +47,9 @@ export function init(blocks) {
 }
 
 /**
+ * Search for a given query in the existing index
  * @param {string} query
- * @returns {import('./types').Block[]}
+ * @returns {import('./types').Tree[]}
  */
 export function search(query) {
 	const escaped = query.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
@@ -53,10 +58,10 @@ export function search(query) {
 	const blocks = indexes
 		.flatMap((index) => index.search(query))
 		.map(lookup)
-		.map((block, rank) => ({ block, rank }))
+		.map((block, rank) => ({ block: /** @type{import('./types').Block} */ (block), rank }))
 		.sort((a, b) => {
-			const a_title_matches = regex.test(a.block.breadcrumbs.at(-1));
-			const b_title_matches = regex.test(b.block.breadcrumbs.at(-1));
+			const a_title_matches = regex.test(/** @type {string} */ (a.block.breadcrumbs.at(-1)));
+			const b_title_matches = regex.test(/** @type {string} */ (b.block.breadcrumbs.at(-1)));
 
 			// massage the order a bit, so that title matches
 			// are given higher priority
@@ -73,7 +78,10 @@ export function search(query) {
 	return results;
 }
 
-/** @param {string} href */
+/**
+ * Get a block with details by its href
+ * @param {string} href
+ */
 export function lookup(href) {
 	return map.get(href);
 }
@@ -81,6 +89,7 @@ export function lookup(href) {
 /**
  * @param {string[]} breadcrumbs
  * @param {import('./types').Block[]} blocks
+ * @returns {import('./types').Tree}
  */
 function tree(breadcrumbs, blocks) {
 	const depth = breadcrumbs.length;
@@ -99,8 +108,8 @@ function tree(breadcrumbs, blocks) {
 
 	return {
 		breadcrumbs,
-		href: hrefs.get(breadcrumbs.join('::')),
-		node,
+		href: /** @type {string} */ (hrefs.get(breadcrumbs.join('::'))),
+		node: /** @type {import('./types').Block} */ (node),
 		children: child_parts.map((part) => tree([...breadcrumbs, part], descendants))
 	};
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bef34bfa..d6841bb6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -12,16 +12,17 @@ importers:
     specifiers:
       '@sveltejs/kit': ^1.3.10
       '@sveltejs/package': ^1.0.2
+      flexsearch: ^0.7.31
       svelte: ^3.55.1
       typescript: ^4.9.5
       vite: ^4.0.4
     devDependencies:
       '@sveltejs/kit': 1.3.10_svelte@3.55.1+vite@4.0.4
       '@sveltejs/package': 1.0.2_4x7phaipmicbaooxtnresslofa
+      flexsearch: 0.7.31
       svelte: 3.55.1
       typescript: 4.9.5
       vite: 4.0.4
-    publishDirectory: package
 
 packages:
 
@@ -1062,6 +1063,10 @@ packages:
       pkg-dir: 4.2.0
     dev: true
 
+  /flexsearch/0.7.31:
+    resolution: {integrity: sha512-XGozTsMPYkm+6b5QL3Z9wQcJjNYxp0CYn3U1gO7dwD6PAqU1SVWZxI9CCg3z+ml3YfqdPnrBehaBrnH2AGKbNA==}
+    dev: true
+
   /for-each/0.3.3:
     resolution: {integrity: sha512-jqYfLp7mo9vIyQf8ykW2v7A+2N4QjeCeI5+Dz9XraiO1ign81wjiH7Fb9vSOWvQfNtmSa4H2RoQTrrXivdUZmw==}
     dependencies: