xs-dev 0.14.2 → 0.15.1

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'
+}

package/docs/src/layouts/MainLayout.astro

@@ -0,0 +1,122 @@
+---
+import HeadCommon from '../components/HeadCommon.astro';
+import HeadSEO from '../components/HeadSEO.astro';
+import Header from '../components/Header/Header.astro';
+import Footer from '../components/Footer/Footer.astro';
+import PageContent from '../components/PageContent/PageContent.astro';
+import LeftSidebar from '../components/LeftSidebar/LeftSidebar.astro';
+import RightSidebar from '../components/RightSidebar/RightSidebar.astro';
+import * as CONFIG from '../config';
+
+const { content = {} } = Astro.props;
+const currentPage = new URL(Astro.request.url).pathname;
+const currentFile = `src/pages${currentPage.replace(/\/$/, '')}.md`;
+const githubEditUrl = CONFIG.GITHUB_EDIT_URL && CONFIG.GITHUB_EDIT_URL + currentFile;
+---
+
+<html dir={content.dir ?? 'ltr'} lang={content.lang ?? 'en-us'} class="initial">
+	<head>
+		<HeadCommon />
+		<HeadSEO {content} canonicalURL={Astro.canonicalURL} />
+		<title>{content.title ? `${content.title} 🚀 ${CONFIG.SITE.title}` : CONFIG.SITE.title}</title>
+		<style>
+			body {
+				width: 100%;
+				display: grid;
+				grid-template-rows: var(--theme-navbar-height) 1fr;
+				--gutter: 0.5rem;
+				--doc-padding: 2rem;
+			}
+			.layout {
+				display: grid;
+				grid-auto-flow: column;
+				grid-template-columns:
+					minmax(var(--gutter), 1fr)
+					minmax(0, var(--max-width))
+					minmax(var(--gutter), 1fr);
+				overflow-x: hidden;
+			}
+			.layout :global(> *) {
+				width: 100%;
+				height: 100%;
+			}
+			.grid-sidebar {
+				height: 100vh;
+				position: sticky;
+				top: 0;
+				padding: 0;
+			}
+			#grid-left {
+				position: fixed;
+				background-color: var(--theme-bg);
+				z-index: 10;
+				display: none;
+			}
+			#grid-main {
+				padding: var(--doc-padding) var(--gutter);
+				grid-column: 2;
+				display: flex;
+				flex-direction: column;
+				height: 100%;
+			}
+			#grid-right {
+				display: none;
+			}
+			:global(.mobile-sidebar-toggle) {
+				overflow: hidden;
+			}
+			:global(.mobile-sidebar-toggle) #grid-left {
+				display: block;
+				top: 2rem;
+			}
+			@media (min-width: 50em) {
+				.layout {
+					overflow: initial;
+					grid-template-columns:
+						20rem
+						minmax(0, var(--max-width));
+					gap: 1em;
+				}
+				#grid-left {
+					display: flex;
+					padding-left: 2rem;
+					position: sticky;
+					grid-column: 1;
+				}
+			}
+
+			@media (min-width: 72em) {
+				.layout {
+					grid-template-columns:
+						20rem
+						minmax(0, var(--max-width))
+						18rem;
+					padding-left: 0;
+					padding-right: 0;
+					margin: 0 auto;
+				}
+				#grid-right {
+					grid-column: 3;
+					display: flex;
+				}
+			}
+		</style>
+	</head>
+
+	<body>
+		<Header {currentPage} />
+		<main class="layout">
+			<aside id="grid-left" class="grid-sidebar" title="Site Navigation">
+				<LeftSidebar {currentPage} />
+			</aside>
+			<div id="grid-main">
+				<PageContent {content} {githubEditUrl}>
+					<slot />
+				</PageContent>
+			</div>
+			<aside id="grid-right" class="grid-sidebar" title="Table of Contents">
+				<RightSidebar {content} {githubEditUrl} />
+			</aside>
+		</main>
+	</body>
+</html>

package/docs/src/pages/en/features/include.md

@@ -0,0 +1,48 @@
+---
+title: Include
+description: Manage modules from Moddable SDK
+layout: ../../../layouts/MainLayout.astro
+---
+
+# Manage modules from Moddable
+
+The Moddable SdK ships with many first-party modules to support various features, peripherals, sensors, etc. The `include` command will update the project `manifest.json` with the selected module:
+
+```
+xs-dev include network/wifi
+```
+
+Or select from available modules:
+
+```
+xs-dev include
+xs-dev include files
+```
+
+## Select a device
+
+When the `--device` flag is present, the module is added to the `platforms` section of the `manifest.json` for the specified device. When `device` is not provided, the module is added to the global manifest section to be used for all devices. For example, the following adds the module for use on `esp32` devices only:
+
+```
+xs-dev include files/flash --device esp32
+```
+
+## Remove a module
+
+Updates the `manifest.json` to remove the module.
+
+```
+xs-dev remove network/wifi
+```
+
+Or remove all modules that contain a string. This removes all modules that contain `"wifi"`.
+
+```
+xs-dev remove wifi
+```
+
+The `--device` flag works for the `remove` command as well:
+
+```
+xs-dev remove network/mqtt --device esp32
+```

package/docs/src/pages/en/features/init.md

@@ -0,0 +1,57 @@
+---
+title: Init
+description: Scaffold new Moddable projects
+layout: ../../../layouts/MainLayout.astro
+---
+
+# Scaffold new Moddable projects
+
+The default template creates a `main.js` and minimally configured `manifest.json` for running in the simulator.
+
+```
+xs-dev init my-project
+```
+
+## TypeScript
+
+The `--typescript` flag will create a project with Moddable types and a `main.ts` to get started:
+
+```
+xs-dev init my-typed-project --typescript
+```
+
+## IO (ECMA 419)
+
+The `--io` flag sets up the project to use the [TC53 IO manifest](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/io/io.md) in the generated `mainfest.json`:
+
+```
+xs-dev init my-io-project --io
+```
+
+## Moddable example
+
+For the `--example` flag, it can be used as a boolean to select a project from the list of available [Moddable examples](https://github.com/Moddable-OpenSource/moddable/tree/public/examples):
+
+```
+xs-dev init my-example-project --example
+```
+
+Or select from a filtered list of projects:
+
+```
+xs-dev init my-http-project --example http
+```
+
+Or if the complete example name is passed, it will be selected by default:
+
+```
+xs-dev init my-mqtt-project --example network/mqtt/mqttbasic
+```
+
+## Overwrite
+
+An existing directory matching the project name can be overwritten with the `--overwrite` flag:
+
+```
+xs-dev init my-existing-project --overwrite
+```

package/docs/src/pages/en/features/run.md

@@ -0,0 +1,63 @@
+---
+title: Run
+description: Build and run Moddable projects or examples
+layout: ../../../layouts/MainLayout.astro
+---
+
+# Run Moddable projects
+
+Within a project directory, the `run` command will invoke [`mcconfig`](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#mcconfig) to generate the `make` file based on the `manifest.json` followed by building and running the project in the current environment simulator:
+
+```
+xs-dev run
+```
+
+When not in the project directory, a path can be passed to `run`:
+
+```
+xs-dev run path/to/project
+```
+
+## Moddable examples
+
+Use the `--example` flag to run a project included with the Moddable SDK:
+
+```
+xs-dev run --example helloworld
+```
+
+The `--list-examples` provides a searchable list of available example projects:
+
+```
+xs-dev run --list-examples
+```
+
+## Select a device target
+
+The `--device` flag allows for selecting a supported [device or simulator target](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md#arguments):
+
+```
+xs-dev run --device esp32
+```
+
+To dynamically select the device, use the `--list-devices` flag:
+
+```
+xs-dev run --list-devices
+```
+
+This can be used in tandem with the `--example` or `--list-examples` flags to run an example project on a connected device:
+
+```
+xs-dev run --list-devices --list-examples
+```
+
+## Select a port address
+
+The `--port` flag accepts a path to port for connected device (defaults to: `UPLOAD_PORT` environment variable):
+
+```
+xs-dev run --port /dev/cu.usbserial-0001 --device esp8266
+```
+
+_This value can be discovered using the [`scan`](./scan) command._

package/docs/src/pages/en/features/scan.md

@@ -0,0 +1,28 @@
+---
+title: Scan
+description: Discover connected device targets
+layout: ../../../layouts/MainLayout.astro
+---
+
+# Discovery available devices
+
+This command will use the [`esptool.py`](https://github.com/espressif/esptool) and/or [`picotool`](https://github.com/raspberrypi/picotool) command line tools to find available device targets connected over USB to the local dev environment.
+
+```
+xs-dev scan
+```
+
+This will provide info with the port address, device name, and discovered features:
+
+```
+✔ Found the following available devices!
+  Port                         Device                      Features
+  /dev/cu.usbserial-0001       ESP8266EX                   WiFi
+  /dev/cu.usbserial-DN02N5XK   ESP32-D0WDQ6 (revision 0)   WiFi, BT, Dual Core, Coding Scheme None
+```
+
+The port can be used with the [`run`](./run) command to specify a device, if multiple are connected:
+
+```
+xs-dev run --port /dev/cu.usbserial-0001 --device esp8266
+```

package/docs/src/pages/en/features/setup.md

@@ -0,0 +1,55 @@
+---
+title: Setup
+description: xs-dev platform setup
+layout: ../../../layouts/MainLayout.astro
+---
+
+# Moddable Platform Setup
+
+This command downloads and builds the [Moddable developer tooling](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/tools/tools.md) for the current OS (Windows support coming soon).
+
+[After installing the CLI](/en/introduction#installation), call the `setup` command:
+
+```
+xs-dev setup
+```
+
+This process mostly automates the instructions provided by [Moddable's "Getting Started" documentation](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/Moddable%20SDK%20-%20Getting%20Started.md) with a few exceptions.
+
+**On macOS:**
+
+[Homebrew](https://brew.sh/) is assumed to be installed.
+
+The [Xcode Command Line tools](https://developer.apple.com/xcode/) are required; `setup` will check for their existence before continuing.
+
+A symlink for [`xsbug.app`](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/xs/xsbug.md) is created in `/Applications` for easy access through Launchpad.
+
+**On Unix environments:**
+
+The [`moddable` git repo](https://github.com/Moddable-OpenSource/moddable) is cloned into `~/.local/share` instead of a new/existing `~/Projects` directory.
+
+## Device Setup
+
+While the `setup` command provides the Moddable SDK for the dev environment, the `--device` flag selects another platform target SDK to set up. It ensures the Moddable SDK has been installed first.
+
+```
+xs-dev setup --device esp32
+```
+
+Use the `--list-devices` flag to get a prompt for supported device tooling to install.
+
+```
+xs-dev setup --list-devices
+```
+
+## Additional related tooling
+
+There are some utilities that are not included in the Moddable SDK or other platform tooling but can be helpful with some common development tasks. The `--tool` flag allows for installing one of these related tools, which may not be easily done from a typical package manager.
+
+**Supported tools:**
+
+[`fontbm`](https://github.com/vladimirgamalyan/fontbm): BMFont compatible, cross-platform (Linux/macOS/Windows) command line bitmap font generator (FreeType2 based render)
+
+```
+xs-dev setup --tool fontbm
+```

package/docs/src/pages/en/features/teardown.md

@@ -0,0 +1,13 @@
+---
+title: Teardown
+description: Clean up dev environment
+layout: ../../../layouts/MainLayout.astro
+---
+
+# Clean up environment changes
+
+Remove all installed git repos and toolchains, unset environment changes. This is all or nothing currently; there's no filter for selecting an individual platform or device tooling.
+
+```
+xs-dev teardown
+```

package/docs/src/pages/en/features/update.md

@@ -0,0 +1,21 @@
+---
+title: Update
+description: Stay up to date with the latest tooling
+layout: ../../../layouts/MainLayout.astro
+---
+
+# SDK & Tooling Updates
+
+Stay up to date with the latest tooling from Moddable and supported device targets. As with the [`setup`](./setup) command, the current dev environment (Mac or Linux) is the default selected target:
+
+```
+xs-dev update
+```
+
+The `--device` flag allows for selecting a different target platform:
+
+```
+xs-dev update --device esp32
+```
+
+_There may be some platforms that are supported by the `setup` command but not `update` yet._