@edgestation/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,205 +1,209 @@
-# @edgestation/sdk
-
-Write widgets for [EdgeStation](https://github.com/chainlist/edgestation), in plain JavaScript, Svelte, React or Vue. EdgeStation is a widget dashboard for a secondary display: made first for the Corsair Xeneon Edge, it works on any other one. The docs call the display it runs on "the Edge", whichever it is.
-
-A widget is a folder with a `manifest.json` and an ES module that EdgeStation loads at runtime. The app hands each widget its `api` when it mounts, so nothing from this package runs inside the app: it gives you
-
-- the TypeScript types of the `api`, the manifest and the widget module,
-- `defineWidget()`, to get those types in plain JavaScript too,
-- adapters that mount a Svelte, React or Vue component as a widget,
-- a Vite plugin that builds the one self-contained `dist/main.js` EdgeStation loads,
-- a JSON Schema for `manifest.json`, for autocomplete and checks in your editor.
-
-What the `api` does, the manifest fields, settings, styling and theming are documented in [Writing a widget](https://github.com/chainlist/edgestation/blob/main/widgets/README.md).
-
-## Start a widget
-
-```bash
-npm install -D @edgestation/sdk vite
-```
-
-```
-my-widget/
-  manifest.json
-  package.json      ("type": "module")
-  vite.config.ts
-  src/main.ts       (or main.js, main.tsx, main.jsx)
-  dist/main.js      (built)
-```
-
-```json
-{
-	"$schema": "./node_modules/@edgestation/sdk/manifest.schema.json",
-	"name": "My widget",
-	"minAppVersion": "0.1.0",
-	"main": "dist/main.js",
-	"size": { "w": 2, "h": 1 }
-}
-```
-
-`minAppVersion` is the oldest EdgeStation that can run the widget: set it to the version of this package you build with (they are released together), and older apps show an error card instead of a broken widget.
-
-### Plain JavaScript or TypeScript
-
-```js
-// vite.config.js
-import { widget } from '@edgestation/sdk/vite';
-import { defineConfig } from 'vite';
-
-export default defineConfig({ plugins: [widget()] });
-```
-
-```js
-// src/main.js
-import { defineWidget } from '@edgestation/sdk';
-
-export default defineWidget({
-	mount(el, api) {
-		api.every(1000, async () => {
-			const { cpu } = await api.system();
-			el.textContent = `${Math.round(cpu.load)} %`;
-		});
-	}
-});
-```
-
-### Svelte 5
-
-```bash
-npm install -D svelte @sveltejs/vite-plugin-svelte
-```
-
-```ts
-// vite.config.ts
-import { widget } from '@edgestation/sdk/vite';
-import { svelte } from '@sveltejs/vite-plugin-svelte';
-import { defineConfig } from 'vite';
-
-export default defineConfig({ plugins: [svelte({ emitCss: false }), widget()] });
-```
-
-```ts
-// src/main.ts
-import { svelteWidget } from '@edgestation/sdk/svelte';
-import Cpu from './Cpu.svelte';
-
-export default svelteWidget(Cpu);
-```
-
-```svelte
-<!-- src/Cpu.svelte -->
-<script lang="ts">
-	import type { WidgetProps } from '@edgestation/sdk';
-
-	let { api }: WidgetProps = $props();
-	let load = $state(0);
-	api.every(1000, async () => (load = (await api.system()).cpu.load));
-</script>
-
-<p>{Math.round(load)} %</p>
-```
-
-`emitCss: false` keeps each component's styles in its JavaScript, and Svelte adds them to the widget's shadow root when it mounts.
-
-### React 19
-
-```bash
-npm install -D react react-dom @vitejs/plugin-react
-```
-
-```ts
-// vite.config.ts
-import { widget } from '@edgestation/sdk/vite';
-import react from '@vitejs/plugin-react';
-import { defineConfig } from 'vite';
-
-export default defineConfig({ plugins: [react(), widget()] });
-```
-
-```tsx
-// src/main.tsx
-import { reactWidget } from '@edgestation/sdk/react';
-import type { WidgetProps } from '@edgestation/sdk';
-import { useEffect, useState } from 'react';
-
-function Cpu({ api }: WidgetProps) {
-	const [load, setLoad] = useState(0);
-	useEffect(() => api.every(1000, async () => setLoad((await api.system()).cpu.load)), []);
-	return <p>{Math.round(load)} %</p>;
-}
-
-export default reactWidget(Cpu);
-```
-
-An error thrown while rendering, that no error boundary of yours catches, shows the widget's error card.
-
-### Vue 3
-
-```bash
-npm install -D vue @vitejs/plugin-vue
-```
-
-```ts
-// vite.config.ts
-import { widget } from '@edgestation/sdk/vite';
-import vue from '@vitejs/plugin-vue';
-import { defineConfig } from 'vite';
-
-export default defineConfig({ plugins: [vue(), widget()] });
-```
-
-```ts
-// src/main.ts
-import { vueWidget } from '@edgestation/sdk/vue';
-import Cpu from './Cpu.vue';
-
-export default vueWidget(Cpu);
-```
-
-```vue
-<!-- src/Cpu.vue -->
-<script setup lang="ts">
-import { ref } from 'vue';
-import type { WidgetProps } from '@edgestation/sdk';
-
-const { api } = defineProps<WidgetProps>();
-const load = ref(0);
-api.every(1000, async () => (load.value = (await api.system()).cpu.load));
-</script>
-
-<template>
-	<p>{{ Math.round(load) }} %</p>
-</template>
-```
-
-Errors Vue catches (rendering, lifecycle hooks, watchers, template event handlers) show the widget's error card.
-
-## Build
-
-```bash
-npx vite build
-```
-
-`widget()` builds the entry into `dist/main.js`, one ES module with every dependency bundled in, your framework's runtime included. CSS your code imports (React, Vue `<style>` blocks) goes to `dist/main.css`: add `"styles": "dist/main.css"` to the manifest so EdgeStation loads it into the widget's shadow root. The build warns when the manifest doesn't point at what it wrote.
-
-Pass `widget({ entry: 'src/other.ts' })` for another entry. For TypeScript to accept CSS imports, add `"types": ["vite/client"]` to your `tsconfig.json`.
-
-## Try it in EdgeStation
-
-EdgeStation loads every folder of `%APPDATA%\com.edgestation.dashboard\widgets\` (Settings → Widgets → Open folder) that has a `manifest.json`; the folder name is the widget's id. Rather than copying your project there, link it, from a Command Prompt:
-
-```bat
-mklink /J "%APPDATA%\com.edgestation.dashboard\widgets\my-widget" C:\path\to\my-widget
-```
-
-Then rebuild on each change, and use Settings → Widgets → Reload Edge to load the new build:
-
-```bash
-npx vite build --watch
-```
-
-To share the widget, ship the folder with `manifest.json`, `dist/` and any files it reads with `api.asset()`.
-
-## Types
-
-Everything is exported from `@edgestation/sdk` as types: `WidgetApi`, `WidgetModule`, `WidgetManifest`, `WidgetProps`, the settings types and the results of `api.system()`, `api.media`, `api.apps` and `api.storage`.
+# @edgestation/sdk
+
+Write widgets for [EdgeStation](https://github.com/chainlist/edgestation), in plain JavaScript, Svelte, React or Vue. EdgeStation is a widget dashboard for a secondary display: made first for the Corsair Xeneon Edge, it works on any other one. The docs call the display it runs on "the Edge", whichever it is.
+
+A widget is a folder with a `manifest.json` and an ES module that EdgeStation loads at runtime. The app hands each widget its `api` when it mounts, so nothing from this package runs inside the app: it gives you
+
+- the TypeScript types of the `api`, the manifest and the widget module,
+- `defineWidget()`, to get those types in plain JavaScript too,
+- adapters that mount a Svelte, React or Vue component as a widget,
+- a Vite plugin that builds the one self-contained `dist/main.js` EdgeStation loads,
+- a JSON Schema for `manifest.json`, for autocomplete and checks in your editor.
+
+What the `api` does, the manifest fields, settings, styling and theming are documented in [Writing a widget](https://github.com/chainlist/edgestation/blob/main/widgets/README.md).
+
+## Start a widget
+
+```bash
+npm install -D @edgestation/sdk vite
+```
+
+```
+my-widget/
+  manifest.json
+  package.json      ("type": "module")
+  vite.config.ts
+  src/main.ts       (or main.js, main.tsx, main.jsx)
+  dist/main.js      (built)
+```
+
+```json
+{
+	"$schema": "./node_modules/@edgestation/sdk/manifest.schema.json",
+	"name": "My widget",
+	"minAppVersion": "0.1.0",
+	"main": "dist/main.js",
+	"size": { "w": 2, "h": 1 }
+}
+```
+
+`minAppVersion` is the oldest EdgeStation that can run the widget: set it to the version of this package you build with (they are released together), and older apps show an error card instead of a broken widget.
+
+### Plain JavaScript or TypeScript
+
+```js
+// vite.config.js
+import { widget } from '@edgestation/sdk/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [widget()] });
+```
+
+```js
+// src/main.js
+import { defineWidget } from '@edgestation/sdk';
+
+export default defineWidget({
+	mount(el, api) {
+		api.every(1000, async () => {
+			const { cpu } = await api.system();
+			el.textContent = `${Math.round(cpu.load)} %`;
+		});
+	}
+});
+```
+
+### Svelte 5
+
+```bash
+npm install -D svelte @sveltejs/vite-plugin-svelte
+```
+
+```ts
+// vite.config.ts
+import { widget } from '@edgestation/sdk/vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [svelte({ emitCss: false }), widget()] });
+```
+
+```ts
+// src/main.ts
+import { svelteWidget } from '@edgestation/sdk/svelte';
+import Cpu from './Cpu.svelte';
+
+export default svelteWidget(Cpu);
+```
+
+```svelte
+<!-- src/Cpu.svelte -->
+<script lang="ts">
+	import type { WidgetProps } from '@edgestation/sdk';
+
+	let props: WidgetProps = $props();
+	// svelte-ignore state_referenced_locally
+	const { api } = props;
+	let load = $state(0);
+	api.every(1000, async () => (load = (await api.system()).cpu.load));
+</script>
+
+<p>{Math.round(load)} %</p>
+```
+
+`emitCss: false` keeps each component's styles in its JavaScript, and Svelte adds them to the widget's shadow root when it mounts.
+
+Read `api` from the props once, at the top of the script. Svelte warns that this only captures the prop's first value (`state_referenced_locally`): that is what you want, since a setting change remounts the widget rather than changing the prop. Taking `api` out of `props` in one statement keeps the warning to that line, which the `svelte-ignore` comment silences. Destructured straight from `$props()`, `api` would raise it at every use.
+
+### React 19
+
+```bash
+npm install -D react react-dom @vitejs/plugin-react
+```
+
+```ts
+// vite.config.ts
+import { widget } from '@edgestation/sdk/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [react(), widget()] });
+```
+
+```tsx
+// src/main.tsx
+import { reactWidget } from '@edgestation/sdk/react';
+import type { WidgetProps } from '@edgestation/sdk';
+import { useEffect, useState } from 'react';
+
+function Cpu({ api }: WidgetProps) {
+	const [load, setLoad] = useState(0);
+	useEffect(() => api.every(1000, async () => setLoad((await api.system()).cpu.load)), []);
+	return <p>{Math.round(load)} %</p>;
+}
+
+export default reactWidget(Cpu);
+```
+
+An error thrown while rendering, that no error boundary of yours catches, shows the widget's error card.
+
+### Vue 3
+
+```bash
+npm install -D vue @vitejs/plugin-vue
+```
+
+```ts
+// vite.config.ts
+import { widget } from '@edgestation/sdk/vite';
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [vue(), widget()] });
+```
+
+```ts
+// src/main.ts
+import { vueWidget } from '@edgestation/sdk/vue';
+import Cpu from './Cpu.vue';
+
+export default vueWidget(Cpu);
+```
+
+```vue
+<!-- src/Cpu.vue -->
+<script setup lang="ts">
+import { ref } from 'vue';
+import type { WidgetProps } from '@edgestation/sdk';
+
+const { api } = defineProps<WidgetProps>();
+const load = ref(0);
+api.every(1000, async () => (load.value = (await api.system()).cpu.load));
+</script>
+
+<template>
+	<p>{{ Math.round(load) }} %</p>
+</template>
+```
+
+Errors Vue catches (rendering, lifecycle hooks, watchers, template event handlers) show the widget's error card.
+
+## Build
+
+```bash
+npx vite build
+```
+
+`widget()` builds the entry into `dist/main.js`, one ES module with every dependency bundled in, your framework's runtime included. CSS your code imports (React, Vue `<style>` blocks) goes to `dist/main.css`: add `"styles": "dist/main.css"` to the manifest so EdgeStation loads it into the widget's shadow root. The build warns when the manifest doesn't point at what it wrote, and when your own code (not your dependencies) calls `setTimeout` or `setInterval`, which keep running while the widget's page is off screen: use `api.after` and `api.every` instead.
+
+Pass `widget({ entry: 'src/other.ts' })` for another entry. For TypeScript to accept CSS imports, add `"types": ["vite/client"]` to your `tsconfig.json`.
+
+## Try it in EdgeStation
+
+EdgeStation loads every folder of `%APPDATA%\com.edgestation.dashboard\widgets\` (Settings → Widgets → Open folder) that has a `manifest.json`; the folder name is the widget's id. Rather than copying your project there, link it, from a Command Prompt:
+
+```bat
+mklink /J "%APPDATA%\com.edgestation.dashboard\widgets\my-widget" C:\path\to\my-widget
+```
+
+Then rebuild on each change, and use Settings → Widgets → Reload Edge to load the new build:
+
+```bash
+npx vite build --watch
+```
+
+To share the widget, ship the folder with `manifest.json`, `dist/` and any files it reads with `api.asset()`.
+
+## Types
+
+Everything is exported from `@edgestation/sdk` as types: `WidgetApi`, `WidgetModule`, `WidgetManifest`, `WidgetProps`, the settings types and the results of `api.system()`, `api.media`, `api.apps` and `api.storage`.

package/dist/vite.d.ts

@@ -16,6 +16,7 @@ export interface WidgetBuildOptions {
  * ```
  *
  * It also replaces `process.env.NODE_ENV`, which React and Vue read and a browser lacks, and
- * warns when `manifest.json` doesn't point at the files it writes.
+ * warns when `manifest.json` doesn't point at the files it writes, or when the widget's own
+ * code (not its dependencies) calls `setTimeout` or `setInterval`, which don't pause with it.
  */
 export declare function widget(options?: WidgetBuildOptions): Plugin;

package/dist/vite.js

@@ -4,6 +4,38 @@ import { join, relative, resolve } from 'node:path';
 const ENTRIES = ['src/main.ts', 'src/main.tsx', 'src/main.js', 'src/main.jsx'];
 /** Forward slashes and no leading `./`, as paths are written in `manifest.json`. */
 const normalize = (path) => path.replace(/\\/g, '/').replace(/^\.\//, '');
+/** What each global timer does that the `api` one doesn't. */
+const TIMERS = {
+    setInterval: "keeps running while the widget's page is off screen or the Edge is frozen, and after " +
+        'the widget unmounts: use api.every instead',
+    setTimeout: "fires even while the widget's page is off screen, and after the widget unmounts: use " +
+        'api.after instead'
+};
+const GLOBALS = new Set(['window', 'globalThis', 'self']);
+/** A file of the widget's own, by its module id: not a dependency, a virtual module or a query. */
+const OWN = /^[^\0?]+\.(?:[cm]?[jt]sx?|svelte|vue)$/;
+/** The global timer that `callee` names (`setTimeout`, `window.setInterval`, ...), if any. */
+function timerName(callee) {
+    const { object, property } = callee;
+    const global = callee.type === 'MemberExpression' &&
+        !callee.computed &&
+        object?.type === 'Identifier' &&
+        GLOBALS.has(object.name ?? '');
+    const name = global ? property?.name : callee.type === 'Identifier' ? callee.name : undefined;
+    return name !== undefined && Object.hasOwn(TIMERS, name) ? name : undefined;
+}
+/** The global timers called anywhere in `node`, an ESTree node or a list of them. */
+function timersCalled(node, found = new Set()) {
+    if (node && typeof node === 'object') {
+        const { type, callee } = node;
+        const name = type === 'CallExpression' && callee ? timerName(callee) : undefined;
+        if (name)
+            found.add(name);
+        for (const child of Object.values(node))
+            timersCalled(child, found);
+    }
+    return found;
+}
 /**
  * Builds the widget into what EdgeStation loads: one self-contained ES module,
  * `dist/main.js`, with every dependency bundled in (frameworks included), plus `dist/main.css`
@@ -14,7 +46,8 @@ const normalize = (path) => path.replace(/\\/g, '/').replace(/^\.\//, '');
  * ```
  *
  * It also replaces `process.env.NODE_ENV`, which React and Vue read and a browser lacks, and
- * warns when `manifest.json` doesn't point at the files it writes.
+ * warns when `manifest.json` doesn't point at the files it writes, or when the widget's own
+ * code (not its dependencies) calls `setTimeout` or `setInterval`, which don't pause with it.
  */
 export function widget(options = {}) {
     let root = process.cwd();
@@ -66,6 +99,20 @@ export function widget(options = {}) {
                     `set "main": "${built('main.js')}".`);
             }
         },
+        // Last, so TypeScript, Svelte and Vue files are plain JavaScript by then, whatever the
+        // plugin order. A dependency's timers are its own business.
+        transform: {
+            order: 'post',
+            handler(code, id) {
+                if (!OWN.test(id) || id.includes('/node_modules/'))
+                    return;
+                if (!/\bset(?:Timeout|Interval)\b/.test(code))
+                    return;
+                for (const name of timersCalled(this.parse(code))) {
+                    this.warn(`${normalize(relative(root, id))} calls ${name}, which ${TIMERS[name]}.`);
+                }
+            }
+        },
         // Not `generateBundle`: Vite's CSS plugin adds main.css to the bundle after it.
         writeBundle(_, bundle) {
             const css = built('main.css');

package/manifest.schema.json

@@ -1,112 +1,112 @@
-{
-	"$schema": "http://json-schema.org/draft-07/schema#",
-	"title": "EdgeStation widget manifest",
-	"description": "The manifest.json of an EdgeStation widget. The widget's id is its folder name.",
-	"type": "object",
-	"required": ["name"],
-	"additionalProperties": false,
-	"properties": {
-		"$schema": { "type": "string" },
-		"name": {
-			"type": "string",
-			"minLength": 1,
-			"description": "Name shown in Settings."
-		},
-		"version": { "type": "string", "description": "The widget's own version." },
-		"description": { "type": "string", "description": "What the widget shows, for Settings." },
-		"author": { "type": "string" },
-		"minAppVersion": {
-			"type": "string",
-			"pattern": "^\\d+\\.\\d+\\.\\d+$",
-			"description": "Oldest EdgeStation version the widget runs on, such as \"0.1.0\": the one whose api it uses. Older versions show the error card instead."
-		},
-		"main": {
-			"type": "string",
-			"default": "main.js",
-			"description": "Entry ES module, relative to the widget folder. It default-exports { mount(el, api) }."
-		},
-		"styles": {
-			"type": "string",
-			"description": "Stylesheet loaded into the widget's shadow root, relative to the widget folder."
-		},
-		"icon": {
-			"type": "string",
-			"description": "Square SVG or PNG on a transparent background, shown in Settings. Only its shape counts: it is drawn in the accent color."
-		},
-		"size": {
-			"type": "object",
-			"description": "Default size in grid cells when the widget is added to a page.",
-			"required": ["w", "h"],
-			"additionalProperties": false,
-			"properties": {
-				"w": { "type": "integer", "minimum": 1 },
-				"h": { "type": "integer", "minimum": 1 }
-			}
-		},
-		"webview": {
-			"type": "boolean",
-			"description": "Lets the widget call api.webview, and gives its settings a Profile choice."
-		},
-		"settings": {
-			"type": "array",
-			"description": "Options the user sets per placement, in display order. The widget reads them from api.settings.",
-			"items": { "oneOf": [{ "$ref": "#/definitions/select" }, { "$ref": "#/definitions/text" }] }
-		}
-	},
-	"definitions": {
-		"key": {
-			"type": "string",
-			"minLength": 1,
-			"description": "Name of the value in api.settings."
-		},
-		"label": { "type": "string", "description": "Shown next to the field." },
-		"when": {
-			"type": "object",
-			"description": "Only show this setting while the named settings have these values.",
-			"additionalProperties": { "type": "string" }
-		},
-		"select": {
-			"type": "object",
-			"description": "One value out of a list.",
-			"required": ["key", "label", "type", "options"],
-			"additionalProperties": false,
-			"properties": {
-				"key": { "$ref": "#/definitions/key" },
-				"label": { "$ref": "#/definitions/label" },
-				"type": { "const": "select" },
-				"options": {
-					"type": "array",
-					"minItems": 1,
-					"items": {
-						"type": "object",
-						"required": ["value", "label"],
-						"additionalProperties": false,
-						"properties": {
-							"value": { "type": "string", "description": "Saved value." },
-							"label": { "type": "string", "description": "Shown label." }
-						}
-					}
-				},
-				"default": {
-					"type": "string",
-					"description": "Value until the user picks one. Defaults to the first option."
-				},
-				"when": { "$ref": "#/definitions/when" }
-			}
-		},
-		"text": {
-			"type": "object",
-			"description": "Free text, such as a URL.",
-			"required": ["key", "label", "type"],
-			"additionalProperties": false,
-			"properties": {
-				"key": { "$ref": "#/definitions/key" },
-				"label": { "$ref": "#/definitions/label" },
-				"type": { "const": "text" },
-				"default": { "type": "string", "description": "Value until the user types one." },
-				"placeholder": { "type": "string", "description": "Hint shown while the field is empty." },
-				"when": { "$ref": "#/definitions/when" }
-			}
-		}
-	}
-}
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "EdgeStation widget manifest",
+	"description": "The manifest.json of an EdgeStation widget. The widget's id is its folder name.",
+	"type": "object",
+	"required": ["name"],
+	"additionalProperties": false,
+	"properties": {
+		"$schema": { "type": "string" },
+		"name": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Name shown in Settings."
+		},
+		"version": { "type": "string", "description": "The widget's own version." },
+		"description": { "type": "string", "description": "What the widget shows, for Settings." },
+		"author": { "type": "string" },
+		"minAppVersion": {
+			"type": "string",
+			"pattern": "^\\d+\\.\\d+\\.\\d+$",
+			"description": "Oldest EdgeStation version the widget runs on, such as \"0.1.0\": the one whose api it uses. Older versions show the error card instead."
+		},
+		"main": {
+			"type": "string",
+			"default": "main.js",
+			"description": "Entry ES module, relative to the widget folder. It default-exports { mount(el, api) }."
+		},
+		"styles": {
+			"type": "string",
+			"description": "Stylesheet loaded into the widget's shadow root, relative to the widget folder."
+		},
+		"icon": {
+			"type": "string",
+			"description": "Square SVG or PNG on a transparent background, shown in Settings. Only its shape counts: it is drawn in the accent color."
+		},
+		"size": {
+			"type": "object",
+			"description": "Default size in grid cells when the widget is added to a page.",
+			"required": ["w", "h"],
+			"additionalProperties": false,
+			"properties": {
+				"w": { "type": "integer", "minimum": 1 },
+				"h": { "type": "integer", "minimum": 1 }
+			}
+		},
+		"webview": {
+			"type": "boolean",
+			"description": "Lets the widget call api.webview, and gives its settings a Profile choice."
+		},
+		"settings": {
+			"type": "array",
+			"description": "Options the user sets per placement, in display order. The widget reads them from api.settings.",
+			"items": { "oneOf": [{ "$ref": "#/definitions/select" }, { "$ref": "#/definitions/text" }] }
+		}
+	},
+	"definitions": {
+		"key": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Name of the value in api.settings."
+		},
+		"label": { "type": "string", "description": "Shown next to the field." },
+		"when": {
+			"type": "object",
+			"description": "Only show this setting while the named settings have these values.",
+			"additionalProperties": { "type": "string" }
+		},
+		"select": {
+			"type": "object",
+			"description": "One value out of a list.",
+			"required": ["key", "label", "type", "options"],
+			"additionalProperties": false,
+			"properties": {
+				"key": { "$ref": "#/definitions/key" },
+				"label": { "$ref": "#/definitions/label" },
+				"type": { "const": "select" },
+				"options": {
+					"type": "array",
+					"minItems": 1,
+					"items": {
+						"type": "object",
+						"required": ["value", "label"],
+						"additionalProperties": false,
+						"properties": {
+							"value": { "type": "string", "description": "Saved value." },
+							"label": { "type": "string", "description": "Shown label." }
+						}
+					}
+				},
+				"default": {
+					"type": "string",
+					"description": "Value until the user picks one. Defaults to the first option."
+				},
+				"when": { "$ref": "#/definitions/when" }
+			}
+		},
+		"text": {
+			"type": "object",
+			"description": "Free text, such as a URL.",
+			"required": ["key", "label", "type"],
+			"additionalProperties": false,
+			"properties": {
+				"key": { "$ref": "#/definitions/key" },
+				"label": { "$ref": "#/definitions/label" },
+				"type": { "const": "text" },
+				"default": { "type": "string", "description": "Value until the user types one." },
+				"placeholder": { "type": "string", "description": "Hint shown while the field is empty." },
+				"when": { "$ref": "#/definitions/when" }
+			}
+		}
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgestation/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Types and build helpers to write widgets for EdgeStation, the secondary display dashboard made for the Corsair Xeneon Edge, in plain JavaScript, Svelte, React or Vue.",
   "keywords": [
     "edgestation",