fix: improve docs example (#4355)

* fix: improve docs example

* final touches

* chore: prettier

* lockfile

* ci?

* downgrade types node

* fresh lockfile

* lockfile and npmrc

* remove debug log

* Merge branch 'main' into docs-template-ts

* merging lockfiles suck

* update lockfile

* satisfy linter

.npmrc

@@ -2,6 +2,7 @@
 prefer-workspace-packages=true
 link-workspace-packages=true
 save-workspace-protocol=false # This prevents the examples to have the `workspace:` prefix
+auto-install-peers=false
 
 shamefully-hoist=true
 # TODO: We would like to move to individual opt-in hoisting, but Astro was not originally

examples/docs/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "dev": "astro dev",
     "start": "astro dev",
+    "check": "astro check && tsc",
     "build": "astro build",
     "preview": "astro preview",
     "astro": "astro"
@@ -20,6 +21,8 @@
   },
   "devDependencies": {
     "@astrojs/preact": "^1.0.2",
+    "@types/node": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
     "@astrojs/react": "^1.1.0",
     "astro": "^1.1.1"
   }

examples/docs/src/components/Footer/AvatarList.astro

@@ -1,12 +1,23 @@
 ---
 // fetch all commits for just this page's path
-const path = 'docs/' + Astro.props.path;
-const url = `https://api.github.com/repos/withastro/astro/commits?path=${path}`;
-const commitsURL = `https://github.com/withastro/astro/commits/main/${path}`;
-
-async function getCommits(url) {
+type Props = {
+	path: string;
+};
+const { path } = Astro.props as Props;
+const resolvedPath = `examples/docs/${path}`;
+const url = `https://api.github.com/repos/withastro/astro/commits?path=${resolvedPath}`;
+const commitsURL = `https://github.com/withastro/astro/commits/main/${resolvedPath}`;
+
+type Commit = {
+	author: {
+		id: string;
+		login: string;
+	};
+};
+
+async function getCommits(url: string) {
 	try {
-		const token = import.meta.env.SNOWPACK_PUBLIC_GITHUB_TOKEN;
+		const token = import.meta.env.SNOWPACK_PUBLIC_GITHUB_TOKEN ?? 'hello';
 		if (!token) {
 			throw new Error(
 				'Cannot find "SNOWPACK_PUBLIC_GITHUB_TOKEN" used for escaping rate-limiting.'
@@ -32,27 +43,24 @@ async function getCommits(url) {
 			);
 		}
 
-		return data;
+		return data as Commit[];
 	} catch (e) {
 		console.warn(`[error]  /src/components/AvatarList.astro 
-    ${e?.message ?? e}`);
-		return new Array();
+    ${(e as any)?.message ?? e}`);
+		return [] as Commit[];
 	}
 }
 
-function removeDups(arr) {
-	if (!arr) {
-		return new Array();
-	}
-	let map = new Map();
+function removeDups(arr: Commit[]) {
+	const map = new Map<string, Commit['author']>();
 
 	for (let item of arr) {
-		let author = item.author;
+		const author = item.author;
 		// Deduplicate based on author.id
 		map.set(author.id, { login: author.login, id: author.id });
 	}
 
-	return Array.from(map.values());
+	return [...map.values()];
 }
 
 const data = await getCommits(url);

examples/docs/src/components/Footer/Footer.astro

@@ -1,16 +1,19 @@
 ---
 import AvatarList from './AvatarList.astro';
-const { path } = Astro.props;
+type Props = {
+	path: string;
+};
+const { path } = Astro.props as Props;
 ---
 
 <footer>
-	<AvatarList {path} />
+	<AvatarList path={path} />
 </footer>
 
 <style>
 	footer {
 		margin-top: auto;
-		padding: 2rem 0;
+		padding: 2rem;
 		border-top: 3px solid var(--theme-divider);
 	}
 </style>

examples/docs/src/components/HeadSEO.astro

@@ -1,46 +1,40 @@
 ---
-import { SITE, OPEN_GRAPH } from '../config';
+import { SITE, OPEN_GRAPH, Frontmatter } from '../config';
+
 export interface Props {
-	frontmatter: any;
-	site: any;
-	canonicalURL: URL | string;
+	frontmatter: Frontmatter;
+	canonicalUrl: URL;
 }
 
-const canonicalURL = new URL(Astro.url.pathname, Astro.site);
-const { frontmatter = {} } = Astro.props;
-const formattedContentTitle = frontmatter.title
-	? `${frontmatter.title} 🚀 ${SITE.title}`
-	: SITE.title;
-const imageSrc = frontmatter?.image?.src ?? OPEN_GRAPH.image.src;
+const { frontmatter, canonicalUrl } = Astro.props as Props;
+const formattedContentTitle = `${frontmatter.title} 🚀 ${SITE.title}`;
+const imageSrc = frontmatter.image?.src ?? OPEN_GRAPH.image.src;
 const canonicalImageSrc = new URL(imageSrc, Astro.site);
-const imageAlt = frontmatter?.image?.alt ?? OPEN_GRAPH.image.alt;
+const imageAlt = frontmatter.image?.alt ?? OPEN_GRAPH.image.alt;
 ---
 
 <!-- Page Metadata -->
-<link rel="canonical" href={canonicalURL} />
+<link rel="canonical" href={canonicalUrl} />
 
 <!-- OpenGraph Tags -->
 <meta property="og:title" content={formattedContentTitle} />
 <meta property="og:type" content="article" />
-<meta property="og:url" content={canonicalURL} />
+<meta property="og:url" content={canonicalUrl} />
 <meta property="og:locale" content={frontmatter.ogLocale ?? SITE.defaultLanguage} />
 <meta property="og:image" content={canonicalImageSrc} />
 <meta property="og:image:alt" content={imageAlt} />
 <meta
 	name="description"
 	property="og:description"
-	content={frontmatter.description ? frontmatter.description : SITE.description}
+	content={frontmatter.description ?? SITE.description}
 />
 <meta property="og:site_name" content={SITE.title} />
 
 <!-- Twitter Tags -->
 <meta name="twitter:card" content="summary_large_image" />
 <meta name="twitter:site" content={OPEN_GRAPH.twitter} />
 <meta name="twitter:title" content={formattedContentTitle} />
-<meta
-	name="twitter:description"
-	content={frontmatter.description ? frontmatter.description : SITE.description}
-/>
+<meta name="twitter:description" content={frontmatter.description ?? SITE.description} />
 <meta name="twitter:image" content={canonicalImageSrc} />
 <meta name="twitter:image:alt" content={imageAlt} />
 

examples/docs/src/components/Header/AstroLogo.astro

@@ -1,5 +1,8 @@
 ---
-const { size } = Astro.props;
+type Props = {
+	size: number;
+};
+const { size } = Astro.props as Props;
 ---
 
 <svg
@@ -14,6 +17,7 @@ const { size } = Astro.props;
 		#flame {
 			fill: var(--theme-text-accent);
 		}
+
 		#a {
 			fill: var(--theme-text-accent);
 		}
@@ -24,11 +28,13 @@ const { size } = Astro.props;
 		fill-rule="evenodd"
 		clip-rule="evenodd"
 		d="M163.008 18.929c1.944 2.413 2.935 5.67 4.917 12.181l43.309 142.27a180.277 180.277 0 00-51.778-17.53l-28.198-95.29a3.67 3.67 0 00-7.042.01l-27.857 95.232a180.225 180.225 0 00-52.01 17.557l43.52-142.281c1.99-6.502 2.983-9.752 4.927-12.16a15.999 15.999 0 016.484-4.798c2.872-1.154 6.271-1.154 13.07-1.154h31.085c6.807 0 10.211 0 13.086 1.157a16.004 16.004 0 016.487 4.806z"
-	></path>
+	>
+	</path>
 	<path
 		id="flame"
 		fill-rule="evenodd"
 		clip-rule="evenodd"
 		d="M168.19 180.151c-7.139 6.105-21.39 10.268-37.804 10.268-20.147 0-37.033-6.272-41.513-14.707-1.602 4.835-1.961 10.367-1.961 13.902 0 0-1.056 17.355 11.015 29.426 0-6.268 5.081-11.349 11.349-11.349 10.743 0 10.731 9.373 10.721 16.977v.679c0 11.542 7.054 21.436 17.086 25.606a23.27 23.27 0 01-2.339-10.2c0-11.008 6.463-15.107 13.974-19.87 5.976-3.79 12.616-8.001 17.192-16.449a31.024 31.024 0 003.743-14.82c0-3.299-.513-6.479-1.463-9.463z"
-	></path>
+	>
+	</path>
 </svg>

examples/docs/src/components/Header/Header.astro

@@ -7,8 +7,12 @@ import SidebarToggle from './SidebarToggle';
 import LanguageSelect from './LanguageSelect';
 import Search from './Search';
 
-const { currentPage } = Astro.props;
-const lang = currentPage && getLanguageFromURL(currentPage);
+type Props = {
+	currentPage: string;
+};
+
+const { currentPage } = Astro.props as Props;
+const lang = getLanguageFromURL(currentPage);
 ---
 
 <header>
@@ -25,11 +29,9 @@ const lang = currentPage && getLanguageFromURL(currentPage);
 		</div>
 		<div style="flex-grow: 1;"></div>
 		{KNOWN_LANGUAGE_CODES.length > 1 && <LanguageSelect lang={lang} client:idle />}
-		{CONFIG.ALGOLIA && (
-			<div class="search-item">
-				<Search client:idle />
-			</div>
-		)}
+		<div class="search-item">
+			<Search client:idle />
+		</div>
 	</nav>
 </header>
 
@@ -101,14 +103,17 @@ const lang = currentPage && getLanguageFromURL(currentPage);
 			position: static;
 			padding: 2rem 0rem;
 		}
+
 		.logo {
 			width: auto;
 			margin: 0;
 			z-index: 0;
 		}
+
 		.logo h1 {
 			display: initial;
 		}
+
 		.menu-toggle {
 			display: none;
 		}
@@ -129,9 +134,11 @@ const lang = currentPage && getLanguageFromURL(currentPage);
 		display: flex;
 		max-width: 200px;
 	}
+
 	:global(.search-item > *) {
 		flex-grow: 1;
 	}
+
 	@media (min-width: 50em) {
 		.search-item {
 			max-width: 400px;

examples/docs/src/components/Header/LanguageSelect.tsx

@@ -1,11 +1,11 @@
-import type { FunctionalComponent } from 'preact';
-import { h } from 'preact';
+/** @jsxImportSource react */
+import type { FunctionComponent } from 'react';
 import './LanguageSelect.css';
 import { KNOWN_LANGUAGES, langPathRegex } from '../../languages';
 
-const LanguageSelect: FunctionalComponent<{ lang: string }> = ({ lang }) => {
+const LanguageSelect: FunctionComponent<{ lang: string }> = ({ lang }) => {
 	return (
-		<div class="language-select-wrapper">
+		<div className="language-select-wrapper">
 			<svg
 				aria-hidden="true"
 				focusable="false"
@@ -25,7 +25,7 @@ const LanguageSelect: FunctionalComponent<{ lang: string }> = ({ lang }) => {
 				/>
 			</svg>
 			<select
-				class="language-select"
+				className="language-select"
 				value={lang}
 				onChange={(e) => {
 					const newLang = e.target.value;
@@ -34,9 +34,9 @@ const LanguageSelect: FunctionalComponent<{ lang: string }> = ({ lang }) => {
 					window.location.pathname = '/' + newLang + actualDest;
 				}}
 			>
-				{Object.keys(KNOWN_LANGUAGES).map((key) => {
+				{Object.entries(KNOWN_LANGUAGES).map(([key, value]) => {
 					return (
-						<option value={KNOWN_LANGUAGES[key]}>
+						<option value={value}>
 							<span>{key}</span>
 						</option>
 					);

examples/docs/src/components/Header/Search.tsx

@@ -1,23 +1,23 @@
-/* jsxImportSource: react */
+/** @jsxImportSource react */
 import { useState, useCallback, useRef } from 'react';
-import * as CONFIG from '../../config';
-import '@docsearch/css/dist/style.css';
+import { ALGOLIA } from '../../config';
+import '@docsearch/css';
 import './Search.css';
 
-// @ts-ignore
-import * as docSearchReact from '@docsearch/react';
-// @ts-ignore
 import { createPortal } from 'react-dom';
+import * as docSearchReact from '@docsearch/react';
 
-export default function Search() {
-	const DocSearchModal = docSearchReact.DocSearchModal || docSearchReact.default.DocSearchModal;
-
-	const useDocSearchKeyboardEvents =
-		docSearchReact.useDocSearchKeyboardEvents || docSearchReact.default.useDocSearchKeyboardEvents;
+/** FIXME: This is still kinda nasty, but DocSearch is not ESM ready. */
+const DocSearchModal =
+	docSearchReact.DocSearchModal || (docSearchReact as any).default.DocSearchModal;
+const useDocSearchKeyboardEvents =
+	docSearchReact.useDocSearchKeyboardEvents ||
+	(docSearchReact as any).default.useDocSearchKeyboardEvents;
 
+export default function Search() {
 	const [isOpen, setIsOpen] = useState(false);
-	const searchButtonRef = useRef();
-	const [initialQuery, setInitialQuery] = useState(null);
+	const searchButtonRef = useRef<HTMLButtonElement>(null);
+	const [initialQuery, setInitialQuery] = useState('');
 
 	const onOpen = useCallback(() => {
 		setIsOpen(true);
@@ -73,9 +73,9 @@ export default function Search() {
 						initialQuery={initialQuery}
 						initialScrollY={window.scrollY}
 						onClose={onClose}
-						indexName={(CONFIG as any).ALGOLIA.indexName}
-						appId={(CONFIG as any).ALGOLIA.appId}
-						apiKey={(CONFIG as any).ALGOLIA.apiKey}
+						indexName={ALGOLIA.indexName}
+						appId={ALGOLIA.appId}
+						apiKey={ALGOLIA.apiKey}
 						transformItems={(items) => {
 							return items.map((item) => {
 								// We transform the absolute URL into a relative URL to

examples/docs/src/components/Header/SidebarToggle.tsx

@@ -1,12 +1,12 @@
+/** @jsxImportSource preact */
 import type { FunctionalComponent } from 'preact';
-import { h, Fragment } from 'preact';
 import { useState, useEffect } from 'preact/hooks';
 
 const MenuToggle: FunctionalComponent = () => {
 	const [sidebarShown, setSidebarShown] = useState(false);
 
 	useEffect(() => {
-		const body = document.getElementsByTagName('body')[0];
+		const body = document.querySelector('body')!;
 		if (sidebarShown) {
 			body.classList.add('mobile-sidebar-toggle');
 		} else {

examples/docs/src/components/Header/SkipToContent.astro

@@ -1,3 +1,7 @@
+---
+type Props = {};
+---
+
 <a href="#article" class="sr-only focus:not-sr-only skiplink"><span>Skip to Content</span></a>
 
 <style>