fix: component docs, fix some type issues

.changeset/gold-days-teach.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/site-kit': patch
+---
+
+fix: component docs, fix some type issues

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"

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>
 

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>

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

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>
 

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>

packages/site-kit/src/lib/components/Shell.svelte

@@ -1,11 +1,20 @@
+<!-- @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';
 	import Icons from './Icons.svelte';
 	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>
 

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>
 

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)}

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"

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';
 

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,14 +78,18 @@ 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);
 }
 
 /**
  * @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))
 	};
 }