xs-dev 0.14.1 → 0.15.0

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

@@ -0,0 +1,65 @@
+import type { FunctionalComponent } from 'preact'
+import { h, Fragment } from 'preact'
+import { useEffect, useRef, useState } from 'preact/hooks'
+import Fuse from 'fuse.js'
+import './Search.css'
+
+const SearchForm: FunctionalComponent = () => {
+  const fuse = useRef(null)
+  const [results, setResults] = useState([])
+
+  const searchContent = (event: SubmitEvent) => {
+    event.preventDefault()
+    const data = Object.fromEntries(
+      new FormData(event.currentTarget as HTMLFormElement)
+    )
+    const result = fuse.current.search(data.search)
+    setResults(result.map(({ item }) => item))
+  }
+
+  useEffect(() => {
+    fetch('/xs-dev/search-index.json')
+      .then((res) => res.json())
+      .then((content) => {
+        const options = { keys: ['title', 'description', 'content'] }
+        fuse.current = new Fuse(content, options)
+      })
+  }, [])
+
+  return (
+    <div class="flex flex-column SearchContainer">
+      <form method="GET" id="search-form" onSubmit={searchContent}>
+        <div role="search" class="flex flex-row">
+          <input
+            type="search"
+            id="search"
+            name="search"
+            aria-label="search documentation content"
+            placeholder="search documentation content"
+            class="SearchContainer-input"
+          />
+          <button type="submit" class="SearchContainer-button">
+            Search
+          </button>
+        </div>
+      </form>
+      <ul
+        class={`SearchContainer-list ${
+          results.length > 0 ? 'has-results' : undefined
+        }`}
+        aria-live="assertive"
+        aria-atomic="true"
+      >
+        {results.map((result) => (
+          <li class="SearchContainer-list_item">
+            <a href={result.url} class="SearchContainer-link">
+              {result.title}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+export default SearchForm

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

@@ -0,0 +1,44 @@
+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];
+		if (sidebarShown) {
+			body.classList.add('mobile-sidebar-toggle');
+		} else {
+			body.classList.remove('mobile-sidebar-toggle');
+		}
+	}, [sidebarShown]);
+
+	return (
+		<button
+			type="button"
+			aria-pressed={sidebarShown ? 'true' : 'false'}
+			id="menu-toggle"
+			onClick={() => setSidebarShown(!sidebarShown)}
+		>
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				width="1em"
+				height="1em"
+				fill="none"
+				viewBox="0 0 24 24"
+				stroke="currentColor"
+			>
+				<path
+					stroke-linecap="round"
+					stroke-linejoin="round"
+					stroke-width="2"
+					d="M4 6h16M4 12h16M4 18h16"
+				/>
+			</svg>
+			<span className="sr-only">Toggle sidebar</span>
+		</button>
+	);
+};
+
+export default MenuToggle;

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

@@ -0,0 +1,22 @@
+<a href="#article" class="sr-only focus:not-sr-only skiplink"><span>Skip to Content</span></a>
+
+<style>
+	.skiplink,
+	.skiplink:focus,
+	.skiplink:focus-visible {
+		position: absolute;
+		padding: 0.25em;
+		font-size: larger;
+		top: 0;
+		left: 0;
+		right: 0;
+		z-index: 9;
+		display: block;
+		text-align: center;
+		background-color: var(--theme-text-accent);
+		color: var(--theme-bg);
+		border-radius: 0.25em;
+		outline: var(--theme-bg) solid 1px;
+		outline-offset: 0;
+	}
+</style>

package/docs/src/components/LeftSidebar/LeftSidebar.astro

@@ -0,0 +1,118 @@
+---
+import { getLanguageFromURL } from '../../languages.ts';
+import { SIDEBAR } from '../../config.ts';
+const { currentPage } = Astro.props;
+const currentPageMatch = currentPage.slice(1);
+const langCode = getLanguageFromURL(currentPage);
+// SIDEBAR is a flat array. Group it by sections to properly render.
+const sidebarSections = SIDEBAR[langCode].reduce((col, item, i) => {
+	// If the first item is not a section header, create a new container section.
+	if (i === 0) {
+		if (!item.header) {
+			const pesudoSection = { text: "" };
+			col.push({ ...pesudoSection, children: [] });
+		}
+	}
+	if (item.header) {
+		col.push({ ...item, children: [] });
+	} else {
+		col[col.length - 1].children.push(item);
+	}
+	return col;
+}, []);
+---
+
+<nav aria-labelledby="grid-left">
+	<ul class="nav-groups">
+		{sidebarSections.map((section) => (
+			<li>
+				<div class="nav-group">
+					<h2 class="nav-group-title">{section.text}</h2>
+					<ul>
+						{section.children.map((child) => (
+							<li class="nav-link">
+								<a href={`${Astro.site.pathname}${child.link}`} aria-current={`${currentPageMatch === child.link ? 'page' : 'false'}`}>
+									{child.text}
+								</a>
+							</li>
+						))}
+					</ul>
+				</div>
+			</li>
+		))}
+	</ul>
+</nav>
+
+<script is:inline>
+	window.addEventListener('DOMContentLoaded', (event) => {
+		var target = document.querySelector('[aria-current="page"]');
+		if (target && target.offsetTop > window.innerHeight - 100) {
+			document.querySelector('.nav-groups').scrollTop = target.offsetTop;
+		}
+	});
+</script>
+
+<style>
+	nav {
+		width: 100%;
+		margin-right: 1rem;
+	}
+	.nav-groups {
+		height: 100%;
+		padding: 2rem 0;
+		overflow-x: visible;
+		overflow-y: auto;
+		max-height: 100vh;
+	}
+
+	.nav-groups > li + li {
+		margin-top: 2rem;
+	}
+
+	.nav-groups > :first-child {
+		padding-top: var(--doc-padding);
+	}
+
+	.nav-groups > :last-child {
+		padding-bottom: 2rem;
+		margin-bottom: var(--theme-navbar-height);
+	}
+
+	.nav-group-title {
+		font-size: 1rem;
+		font-weight: 700;
+		padding: 0.1rem 1rem;
+		text-transform: uppercase;
+		margin-bottom: 0.5rem;
+	}
+
+	.nav-link a {
+		font-size: 1rem;
+		margin: 1px;
+		padding: 0.3rem 1rem;
+		font: inherit;
+		color: inherit;
+		text-decoration: none;
+		display: block;
+	}
+	.nav-link a:hover,
+	.nav-link a:focus {
+		background-color: var(--theme-bg-hover);
+	}
+
+	.nav-link a[aria-current='page'] {
+		color: var(--theme-text-accent);
+		background-color: var(--theme-bg-accent);
+		font-weight: 600;
+	}
+
+	:global(:root.theme-dark) .nav-link a[aria-current='page'] {
+		color: hsla(var(--color-base-white), 100%, 1);
+	}
+
+	@media (min-width: 50em) {
+		.nav-groups {
+			padding: 0;
+		}
+	}
+</style>

package/docs/src/components/PageContent/PageContent.astro

@@ -0,0 +1,41 @@
+---
+import MoreMenu from '../RightSidebar/MoreMenu.astro';
+import TableOfContents from '../RightSidebar/TableOfContents.tsx';
+
+const { content, githubEditUrl } = Astro.props;
+const title = content.title;
+const headers = content.astro.headers;
+---
+
+<article id="article" class="content">
+	<section class="main-section">
+		<h1 class="content-title" id="overview">{title}</h1>
+		<slot />
+	</section>
+	<nav class="block sm:hidden">
+		<MoreMenu editHref={githubEditUrl} />
+	</nav>
+</article>
+
+<style>
+	.content {
+		padding: 0;
+		max-width: 75ch;
+		width: 100%;
+		height: 100%;
+		display: flex;
+		flex-direction: column;
+	}
+	.content > section {
+		margin-bottom: 4rem;
+	}
+	.block {
+		display: block;
+	}
+
+	@media (min-width: 50em) {
+		.sm\:hidden {
+			display: none;
+		}
+	}
+</style>

package/docs/src/components/RightSidebar/MoreMenu.astro

@@ -0,0 +1,70 @@
+---
+import ThemeToggleButton from './ThemeToggleButton.tsx';
+import * as CONFIG from '../../config';
+const { editHref } = Astro.props;
+const showMoreSection = CONFIG.COMMUNITY_INVITE_URL || editHref;
+---
+
+{showMoreSection && <h2 class="heading">More</h2>}
+<ul>
+	{editHref && (
+		<li class={`header-link depth-2`}>
+			<a class="edit-on-github" href={editHref} target="_blank">
+				<svg
+					aria-hidden="true"
+					focusable="false"
+					data-prefix="fas"
+					data-icon="pen"
+					class="svg-inline--fa fa-pen fa-w-16"
+					role="img"
+					xmlns="http://www.w3.org/2000/svg"
+					viewBox="0 0 512 512"
+					height="1em"
+					width="1em"
+				>
+					<path
+						fill="currentColor"
+						d="M290.74 93.24l128.02 128.02-277.99 277.99-114.14 12.6C11.35 513.54-1.56 500.62.14 485.34l12.7-114.22 277.9-277.88zm207.2-19.06l-60.11-60.11c-18.75-18.75-49.16-18.75-67.91 0l-56.55 56.55 128.02 128.02 56.55-56.55c18.75-18.76 18.75-49.16 0-67.91z"
+					></path>
+				</svg>
+				<span>Edit this page</span>
+			</a>
+		</li>
+	)}
+	{CONFIG.COMMUNITY_INVITE_URL && (
+		<li class={`header-link depth-2`}>
+			<a href={CONFIG.COMMUNITY_INVITE_URL} target="_blank">
+				<svg
+					aria-hidden="true"
+					focusable="false"
+					data-prefix="fas"
+					data-icon="comment-alt"
+					class="svg-inline--fa fa-comment-alt fa-w-16"
+					role="img"
+					xmlns="http://www.w3.org/2000/svg"
+					viewBox="0 0 512 512"
+					height="1em"
+					width="1em"
+				>
+					<path
+						fill="currentColor"
+						d="M448 0H64C28.7 0 0 28.7 0 64v288c0 35.3 28.7 64 64 64h96v84c0 9.8 11.2 15.5 19.1 9.7L304 416h144c35.3 0 64-28.7 64-64V64c0-35.3-28.7-64-64-64z"
+					></path>
+				</svg>
+				<span>Join our community</span>
+			</a>
+		</li>
+	)}
+</ul>
+<div style="margin: 2rem 0; text-align: center;">
+	<ThemeToggleButton client:visible />
+</div>
+
+<style>
+	.edit-on-github {
+		text-decoration: none;
+		font: inherit;
+		color: inherit;
+		font-size: 1rem;
+	}
+</style>

package/docs/src/components/RightSidebar/RightSidebar.astro

@@ -0,0 +1,27 @@
+---
+import TableOfContents from './TableOfContents.tsx';
+import MoreMenu from './MoreMenu.astro';
+const { content, githubEditUrl } = Astro.props;
+const headers = content.astro.headers;
+---
+
+<nav class="sidebar-nav" aria-labelledby="grid-right">
+	<div class="sidebar-nav-inner">
+		<TableOfContents client:media="(min-width: 50em)" {headers} />
+		<MoreMenu editHref={githubEditUrl} />
+	</div>
+</nav>
+
+<style>
+	.sidebar-nav {
+		width: 100%;
+		position: sticky;
+		top: 0;
+	}
+	.sidebar-nav-inner {
+		height: 100%;
+		padding: 0;
+		padding-top: var(--doc-padding);
+		overflow: auto;
+	}
+</style>

package/docs/src/components/RightSidebar/TableOfContents.tsx

@@ -0,0 +1,49 @@
+import type { FunctionalComponent } from 'preact';
+import { h, Fragment } from 'preact';
+import { useState, useEffect, useRef } from 'preact/hooks';
+
+const TableOfContents: FunctionalComponent<{ headers: any[] }> = ({ headers = [] }) => {
+	const itemOffsets = useRef([]);
+	const [activeId, setActiveId] = useState<string>(undefined);
+
+	useEffect(() => {
+		const getItemOffsets = () => {
+			const titles = document.querySelectorAll('article :is(h1, h2, h3, h4)');
+			itemOffsets.current = Array.from(titles).map((title) => ({
+				id: title.id,
+				topOffset: title.getBoundingClientRect().top + window.scrollY,
+			}));
+		};
+
+		getItemOffsets();
+		window.addEventListener('resize', getItemOffsets);
+
+		return () => {
+			window.removeEventListener('resize', getItemOffsets);
+		};
+	}, []);
+
+	return (
+		<>
+			<h2 class="heading">On this page</h2>
+			<ul>
+				<li class={`header-link depth-2 ${activeId === 'overview' ? 'active' : ''}`.trim()}>
+					<a href="#overview">Overview</a>
+				</li>
+				{headers
+					.filter(({ depth }) => depth > 1 && depth < 4)
+					.map((header) => (
+						<li
+							class={`header-link depth-${header.depth} ${
+								activeId === header.slug ? 'active' : ''
+							}`.trim()}
+						>
+							<a href={`#${header.slug}`}>{header.text}</a>
+						</li>
+					))}
+			</ul>
+		</>
+	);
+};
+
+export default TableOfContents;

package/docs/src/components/RightSidebar/ThemeToggleButton.css

@@ -0,0 +1,37 @@
+.theme-toggle {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.25em;
+	padding: 0.33em 0.67em;
+	border-radius: 99em;
+	background-color: var(--theme-code-inline-bg);
+}
+
+.theme-toggle > label:focus-within {
+	outline: 2px solid transparent;
+	box-shadow: 0 0 0 0.08em var(--theme-accent), 0 0 0 0.12em white;
+}
+
+.theme-toggle > label {
+	color: var(--theme-code-inline-text);
+	position: relative;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	opacity: 0.5;
+}
+
+.theme-toggle .checked {
+	color: var(--theme-accent);
+	opacity: 1;
+}
+
+input[name='theme-toggle'] {
+	position: absolute;
+	opacity: 0;
+	top: 0;
+	right: 0;
+	bottom: 0;
+	left: 0;
+	z-index: -1;
+}

package/docs/src/components/RightSidebar/ThemeToggleButton.tsx

@@ -0,0 +1,83 @@
+import type { FunctionalComponent } from 'preact';
+import { h, Fragment } from 'preact';
+import { useState, useEffect } from 'preact/hooks';
+import './ThemeToggleButton.css';
+
+const themes = ['light', 'dark'];
+
+const icons = [
+	<svg
+		xmlns="http://www.w3.org/2000/svg"
+		width="20"
+		height="20"
+		viewBox="0 0 20 20"
+		fill="currentColor"
+	>
+		<path
+			fillRule="evenodd"
+			d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4 8a4 4 0 11-8 0 4 4 0 018 0zm-.464 4.95l.707.707a1 1 0 001.414-1.414l-.707-.707a1 1 0 00-1.414 1.414zm2.12-10.607a1 1 0 010 1.414l-.706.707a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 0zM17 11a1 1 0 100-2h-1a1 1 0 100 2h1zm-7 4a1 1 0 011 1v1a1 1 0 11-2 0v-1a1 1 0 011-1zM5.05 6.464A1 1 0 106.465 5.05l-.708-.707a1 1 0 00-1.414 1.414l.707.707zm1.414 8.486l-.707.707a1 1 0 01-1.414-1.414l.707-.707a1 1 0 011.414 1.414zM4 11a1 1 0 100-2H3a1 1 0 000 2h1z"
+			clipRule="evenodd"
+		/>
+	</svg>,
+	<svg
+		xmlns="http://www.w3.org/2000/svg"
+		width="20"
+		height="20"
+		viewBox="0 0 20 20"
+		fill="currentColor"
+	>
+		<path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z" />
+	</svg>,
+];
+
+const ThemeToggle: FunctionalComponent = () => {
+	const [theme, setTheme] = useState(() => {
+		if (import.meta.env.SSR) {
+			return undefined;
+		}
+		if (typeof localStorage !== 'undefined' && localStorage.getItem('theme')) {
+			return localStorage.getItem('theme');
+		}
+		if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+			return 'dark';
+		}
+		return 'light';
+	});
+
+	useEffect(() => {
+		const root = document.documentElement;
+		if (theme === 'light') {
+			root.classList.remove('theme-dark');
+		} else {
+			root.classList.add('theme-dark');
+		}
+	}, [theme]);
+
+	return (
+		<div class="theme-toggle">
+			{themes.map((t, i) => {
+				const icon = icons[i];
+				const checked = t === theme;
+				return (
+					<label className={checked ? ' checked' : ''}>
+						{icon}
+						<input
+							type="radio"
+							name="theme-toggle"
+							checked={checked}
+							value={t}
+							title={`Use ${t} theme`}
+							aria-label={`Use ${t} theme`}
+							onChange={() => {
+								localStorage.setItem('theme', t);
+								setTheme(t);
+							}}
+						/>
+					</label>
+				);
+			})}
+		</div>
+	);
+};
+
+export default ThemeToggle;

package/docs/src/config.ts

@@ -0,0 +1,43 @@
+export const SITE = {
+  title: 'xs-dev Documentation',
+  description: 'CLI for automating the setup and usage of Moddable XS tools',
+  defaultLanguage: 'en_US',
+}
+
+export const OPEN_GRAPH = {
+  twitter: 'hipsterbrown',
+  github: 'hipsterbrown',
+}
+
+export const KNOWN_LANGUAGES = {
+  English: 'en',
+}
+
+// Uncomment this to add an "Edit this page" button to every page of documentation.
+export const GITHUB_EDIT_URL = `https://github.com/hipsterbrown/xs-dev/blob/main/docs/`
+
+// Uncomment this to add an "Join our Community" button to every page of documentation.
+// export const COMMUNITY_INVITE_URL = `https://astro.build/chat`;
+
+// Uncomment this to enable site search.
+// See "Algolia" section of the README for more information.
+// export const ALGOLIA = {
+//   indexName: 'XXXXXXXXXX',
+//   appId: 'XXXXXXXXXX',
+//   apiKey: 'XXXXXXXXXX',
+// }
+
+export const SIDEBAR = {
+  en: [
+    { text: '', header: true },
+    { text: 'Features', header: true },
+    { text: 'Introduction', link: 'en/introduction' },
+    { text: 'Setup', link: 'en/features/setup' },
+    { text: 'Updates', link: 'en/features/update' },
+    { text: 'Teardown', link: 'en/features/teardown' },
+    { text: 'Device Discovery', link: 'en/features/scan' },
+    { text: 'Project Creation', link: 'en/features/init' },
+    { text: 'Build & Run', link: 'en/features/run' },
+    { text: 'SDK Module Management', link: 'en/features/include' },
+  ],
+}

package/docs/src/languages.ts

@@ -0,0 +1,10 @@
+import { KNOWN_LANGUAGES } from './config';
+
+export { KNOWN_LANGUAGES };
+export const KNOWN_LANGUAGE_CODES = Object.values(KNOWN_LANGUAGES);
+export const langPathRegex = /\/([a-z]{2}-?[A-Z]{0,2})\//;
+
+export function getLanguageFromURL(pathname: string) {
+	const langCodeMatch = pathname.match(langPathRegex);
+	return langCodeMatch ? langCodeMatch[1] : 'en';
+}