@tsplc/debug 0.2.16 → 0.2.18

package/src/ui/dom.ts

@@ -1,142 +1,197 @@
 import type { DeviceState } from "../api.ts";
 import type { DebugDevice, SourceRange } from "../manifest.ts";
 import {
-  formatReadAt,
-  formatValue,
-  recordLocation,
-  sourceLocation,
-  valueStateLabels,
+	formatReadAt,
+	formatValue,
+	recordLocation,
+	sourceLocation,
+	valueStateLabels,
 } from "./format.ts";
 import type { Store, Topic } from "./store.ts";
 import type { TreeNode } from "./tree.ts";
 
 type Child = Node | string | null | undefined | false;
-type Attribute = string | number | boolean | undefined | ((event: Event) => void);
+type Attribute =
+	string | number | boolean | undefined | ((event: Event) => void);
 
 export const h = <K extends keyof HTMLElementTagNameMap>(
-  tag: K,
-  attributes: Record<string, Attribute> = {},
-  ...children: Child[]
+	tag: K,
+	attributes: Record<string, Attribute> = {},
+	...children: Child[]
 ): HTMLElementTagNameMap[K] => {
-  const element = document.createElement(tag);
-  for (const [name, value] of Object.entries(attributes)) {
-    if (value === undefined || value === false) continue;
-    if (typeof value === "function") element.addEventListener(name.slice(2), value);
-    else element.setAttribute(name, value === true ? "" : String(value));
-  }
-  return fill(element, ...children);
+	const element = document.createElement(tag);
+	for (const [name, value] of Object.entries(attributes)) {
+		if (value === undefined || value === false) {
+			continue;
+		}
+		if (typeof value === "function") {
+			element.addEventListener(name.slice(2), value);
+		} else {
+			element.setAttribute(name, value === true ? "" : String(value));
+		}
+	}
+	return fill(element, ...children);
 };
 
 /** Replaces an element's children, skipping the absent ones. */
 export const fill = <E extends Element>(element: E, ...children: Child[]) => {
-  element.replaceChildren(...children.filter((child): child is Node | string => Boolean(child)));
-  return element;
+	element.replaceChildren(
+		...children.filter((child): child is Node | string => Boolean(child)),
+	);
+	return element;
 };
 
 /** A page: built once per route, then told which store topics changed each frame. */
 export interface View {
-  element: HTMLElement;
-  update(topics: Set<Topic>): void;
-  dispose?(): void;
+	element: HTMLElement;
+	update(topics: Set<Topic>): void;
+	dispose?(): void;
 }
 
 export const empty = (text: string) => h("p", { class: "empty" }, text);
 
+/** A table of `class` (`grid`, styled as a panel) with a header row of `columns`. */
+export const table = (
+	attributes: { class: string },
+	columns: string[],
+	body: HTMLElement,
+) =>
+	h(
+		"table",
+		attributes,
+		h("thead", {}, h("tr", {}, ...columns.map((label) => h("th", {}, label)))),
+		body,
+	);
+
 const locationLink = (
-  { label, href }: { label: string; href?: string },
-  title: string,
-  text?: string,
+	{ label, href }: { label: string; href?: string },
+	title: string,
+	text?: string,
 ) =>
-  href
-    ? h("a", { class: "src", href, title: `Open ${title} in VS Code` }, text ?? label)
-    : h("span", { class: "src", title }, text ?? label);
+	href
+		? h(
+				"a",
+				{ class: "src", href, title: `Open ${title} in VS Code` },
+				text ?? label,
+			)
+		: h("span", { class: "src", title }, text ?? label);
 
 export const sourceLink = (store: Store, range: SourceRange, text?: string) => {
-  const location = sourceLocation(store.manifest, store.session.projectRoot, range);
-  return locationLink(location, location.label, text);
+	const location = sourceLocation(
+		store.manifest,
+		store.session.projectRoot,
+		range,
+	);
+	return locationLink(location, location.label, text);
 };
 
 /** A telemetry record's `source`, a project-relative `file:line`. */
 export const recordSourceLink = (store: Store, source: string) =>
-  locationLink(recordLocation(store.session.projectRoot, source), source);
+	locationLink(recordLocation(store.session.projectRoot, source), source);
 
-const variableHref = (path: string) => `#/variables?path=${encodeURIComponent(path)}`;
+export const variableHref = (path: string) =>
+	`#/variables?path=${encodeURIComponent(path)}`;
+
+export const deviceHref = (id: string) =>
+	`#/hardware/${encodeURIComponent(id)}`;
 
 export const pathLink = (path: string, text: Node | string = path) =>
-  h("a", { class: "path", href: variableHref(path), title: `Show ${path} in Variables` }, text);
+	h(
+		"a",
+		{
+			class: "path",
+			href: variableHref(path),
+			title: `Show ${path} in Variables`,
+		},
+		text,
+	);
 
 /** A path that wraps only between its segments. */
 export const wrappingPath = (path: string) =>
-  h("span", {}, ...path.split(/(?=[.[])/).flatMap((segment) => [h("wbr"), segment]));
+	h(
+		"span",
+		{},
+		...path.split(/(?=[.[])/).flatMap((segment) => [h("wbr"), segment]),
+	);
 
 const setText = (element: HTMLElement, text: string) => {
-  if (element.textContent !== text) element.textContent = text;
+	if (element.textContent !== text) {
+		element.textContent = text;
+	}
 };
 const setClass = (element: HTMLElement, name: string) => {
-  if (element.className !== name) element.className = name;
+	if (element.className !== name) {
+		element.className = name;
+	}
 };
 
 /** A variable's value and its quality and age, kept current by `update()` from the store. */
 export class LiveValue {
-  readonly value = h("span");
-  readonly meta = h("span");
-
-  constructor(
-    private readonly store: Store,
-    readonly node: TreeNode,
-  ) {
-    this.update();
-  }
-
-  /** Whether the stream should carry this path. */
-  get subscribed() {
-    return this.node.readable && !this.node.constant;
-  }
-
-  update() {
-    const { node, store } = this;
-    if (node.constant)
-      return this.show(
-        "constant",
-        formatValue(store.manifest, node.type, node.constant.value),
-        "constant",
-      );
-    if (!node.readable)
-      return this.show(
-        "unavailable",
-        "—",
-        "not readable",
-        "This build can't read it from the controller",
-      );
-    const { sample, state } = store.live(node.path);
-    if (!sample) return this.show("unavailable", "—", "not read", "Not read yet");
-    const meta =
-      state === "unavailable" || state === "bad"
-        ? valueStateLabels[state]
-        : `${valueStateLabels[state]} · ${formatReadAt(sample.receivedAt)}`;
-    this.show(
-      state,
-      formatValue(store.manifest, node.type, sample.value),
-      meta,
-      `${sample.status}\nread ${sample.receivedAt}`,
-    );
-  }
-
-  private show(state: string, value: string, meta: string, title?: string) {
-    setClass(this.value, `value s-${state}`);
-    setClass(this.meta, `meta s-${state}`);
-    setText(this.value, value);
-    setText(this.meta, meta);
-    if (title !== undefined && this.meta.title !== title) this.meta.title = title;
-  }
+	readonly value = h("span");
+	readonly meta = h("span");
+
+	constructor(
+		private readonly store: Store,
+		readonly node: TreeNode,
+	) {
+		this.update();
+	}
+
+	/** Whether the stream should carry this path. */
+	get subscribed() {
+		return this.node.readable && !this.node.constant;
+	}
+
+	update() {
+		const { node, store } = this;
+		if (node.constant) {
+			return this.show(
+				"constant",
+				formatValue(store.manifest, node.type, node.constant.value),
+				"constant",
+			);
+		}
+		if (!node.readable) {
+			return this.show(
+				"unavailable",
+				"—",
+				"not readable",
+				"This build can't read it from the controller",
+			);
+		}
+		const { sample, state } = store.live(node.path);
+		if (!sample) {
+			return this.show("unavailable", "—", "not read", "Not read yet");
+		}
+		const meta =
+			state === "unavailable" || state === "bad"
+				? valueStateLabels[state]
+				: `${valueStateLabels[state]} · ${formatReadAt(sample.receivedAt)}`;
+		this.show(
+			state,
+			formatValue(store.manifest, node.type, sample.value),
+			meta,
+			`${sample.status}\nread ${sample.receivedAt}`,
+		);
+	}
+
+	private show(state: string, value: string, meta: string, title?: string) {
+		setClass(this.value, `value s-${state}`);
+		setClass(this.meta, `meta s-${state}`);
+		setText(this.value, value);
+		setText(this.meta, meta);
+		if (title !== undefined && this.meta.title !== title) {
+			this.meta.title = title;
+		}
+	}
 }
 
 export type Health = "ok" | "fault" | "stale" | "unknown";
 
 interface HealthView {
-  health: Health;
-  text: string;
-  detail: string;
+	health: Health;
+	text: string;
+	detail: string;
 }
 
 /**
@@ -144,25 +199,51 @@ interface HealthView {
  * login" while nothing can read it, never "OK" by default.
  */
 export const deviceHealth = (store: Store, device: DebugDevice): HealthView => {
-  const state: DeviceState | undefined = store.devices.get(device.id);
-  const { connection } = store.session;
-  if (!device.health)
-    return {
-      health: "unknown",
-      text: "unknown",
-      detail: "This build reads no health for this device",
-    };
-  if (connection.state === "unavailable")
-    return { health: "unknown", text: "needs login", detail: connection.error ?? "" };
-  if (!state || state.health.state === "unknown")
-    return { health: "unknown", text: "unknown", detail: "The driver's state has not been read" };
-  const { health } = state;
-  const detail = [health.name, health.message].filter(Boolean).join(" · ");
-  if (health.state === "stale") return { health: "stale", text: "stale", detail };
-  if (!store.connected || health.quality !== "good")
-    return { health: "stale", text: `stale, was ${health.state}`, detail };
-  return { health: health.state, text: health.state === "ok" ? "OK" : health.state, detail };
+	const state: DeviceState | undefined = store.devices.get(device.id);
+	const { connection } = store.session;
+	if (!device.health) {
+		return {
+			health: "unknown",
+			text: "unknown",
+			detail: "This build reads no health for this device",
+		};
+	}
+	if (connection.state === "unavailable") {
+		return {
+			health: "unknown",
+			text: "needs login",
+			detail: connection.error ?? "",
+		};
+	}
+	if (!state || state.health.state === "unknown") {
+		return {
+			health: "unknown",
+			text: "unknown",
+			detail: "The driver's state has not been read",
+		};
+	}
+	const { health } = state;
+	const detail = [health.name, health.message].filter(Boolean).join(" · ");
+	if (health.state === "stale") {
+		return { health: "stale", text: "stale", detail };
+	}
+	if (!store.connected || health.quality !== "good") {
+		return { health: "stale", text: `stale, was ${health.state}`, detail };
+	}
+	return {
+		health: health.state,
+		text: health.state === "ok" ? "OK" : health.state,
+		detail,
+	};
 };
 
+/** The devices whose driver state this build reads: the ones a page listing health asks for. */
+export const devicesWithHealth = (store: Store) =>
+	store.manifest.devices.filter((device) => device.health).map(({ id }) => id);
+
 export const healthBadge = (health: HealthView) =>
-  h("span", { class: `badge h-${health.health}`, title: health.detail }, health.text);
+	h(
+		"span",
+		{ class: `badge h-${health.health}`, title: health.detail },
+		health.text,
+	);

package/src/ui/format.ts

@@ -3,123 +3,178 @@ import type { DebugManifest, SourceRange } from "../manifest.ts";
 import { typeOf } from "../paths.ts";
 
 /** How a value is shown: each state has its own styling and label, so none passes for live. */
-export type ValueState = "live" | "uncertain" | "bad" | "stale" | "unavailable" | "constant";
+export type ValueState =
+	"live" | "uncertain" | "bad" | "stale" | "unavailable" | "constant";
 
 export const valueStateLabels: Record<ValueState, string> = {
-  live: "good",
-  uncertain: "uncertain",
-  bad: "bad",
-  stale: "stale",
-  unavailable: "unavailable",
-  constant: "constant",
+	live: "good",
+	uncertain: "uncertain",
+	bad: "bad",
+	stale: "stale",
+	unavailable: "unavailable",
+	constant: "constant",
 };
 
 /** A sample is stale when the controller connection is down or the sample is older than three sample intervals. */
 export const valueState = (
-  quality: Quality,
-  ageMs: number,
-  context: { connected: boolean; intervalMs: number },
+	quality: Quality,
+	ageMs: number,
+	context: { connected: boolean; intervalMs: number },
 ): ValueState => {
-  if (quality === "unavailable") return "unavailable";
-  if (!context.connected || ageMs > 3 * context.intervalMs) return "stale";
-  if (quality === "bad") return "bad";
-  if (quality === "uncertain") return "uncertain";
-  return "live";
+	if (quality === "unavailable") {
+		return "unavailable";
+	}
+	if (!context.connected || ageMs > 3 * context.intervalMs) {
+		return "stale";
+	}
+	if (quality === "bad") {
+		return "bad";
+	}
+	if (quality === "uncertain") {
+		return "uncertain";
+	}
+	return "live";
 };
 
 export const formatAge = (ms: number) => {
-  if (ms < 1000) return "now";
-  if (ms < 60_000) return `${Math.floor(ms / 1000)} s ago`;
-  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)} min ago`;
-  return `${Math.floor(ms / 3_600_000)} h ago`;
+	if (ms < 1000) {
+		return "now";
+	}
+	if (ms < 60_000) {
+		return `${Math.floor(ms / 1000)} s ago`;
+	}
+	if (ms < 3_600_000) {
+		return `${Math.floor(ms / 60_000)} min ago`;
+	}
+	return `${Math.floor(ms / 3_600_000)} h ago`;
 };
 
 export const formatDuration = (ms: number) => {
-  if (ms < 1000) return `${Math.round(ms)} ms`;
-  if (ms < 60_000) return `${(ms / 1000).toFixed(1)} s`;
-  return `${Math.floor(ms / 60_000)} min ${Math.floor((ms % 60_000) / 1000)} s`;
+	if (ms < 1000) {
+		return `${Math.round(ms)} ms`;
+	}
+	if (ms < 60_000) {
+		return `${(ms / 1000).toFixed(1)} s`;
+	}
+	return `${Math.floor(ms / 60_000)} min ${Math.floor((ms % 60_000) / 1000)} s`;
 };
 
 /** How often values are read: `250 ms`, `1 s`, `1.5 s`. */
-export const formatInterval = (ms: number) => (ms < 1000 ? `${ms} ms` : `${ms / 1000} s`);
+export const formatInterval = (ms: number) =>
+	ms < 1000 ? `${ms} ms` : `${ms / 1000} s`;
 
 /** Local time of day with milliseconds, for ordering events by eye. */
 export const formatClock = (iso: string) => {
-  const date = new Date(iso);
-  const pad = (value: number, width = 2) => String(value).padStart(width, "0");
-  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+	const date = new Date(iso);
+	const pad = (value: number, width = 2) => String(value).padStart(width, "0");
+	return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
 };
 
 /** When a value was read, to the second: `read 14:03:27`. */
-export const formatReadAt = (iso: string) => `read ${formatClock(iso).slice(0, 8)}`;
+export const formatReadAt = (iso: string) =>
+	`read ${formatClock(iso).slice(0, 8)}`;
 
 /** A value of unknown type: booleans as IEC literals, strings quoted. */
 export const formatScalar = (value: unknown): string => {
-  if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
-  if (typeof value === "number")
-    return Number.isInteger(value) ? String(value) : String(Number(value.toPrecision(6)));
-  if (typeof value === "string") return JSON.stringify(value);
-  if (value === null || value === undefined) return "—";
-  return JSON.stringify(value);
+	if (typeof value === "boolean") {
+		return value ? "TRUE" : "FALSE";
+	}
+	if (typeof value === "number") {
+		return Number.isInteger(value)
+			? String(value)
+			: String(Number(value.toPrecision(6)));
+	}
+	if (typeof value === "string") {
+		return JSON.stringify(value);
+	}
+	if (value === null || value === undefined) {
+		return "—";
+	}
+	return JSON.stringify(value);
 };
 
 /** A value in the program's terms: enum members by name, whether the host decoded them already or not. */
-export const formatValue = (manifest: DebugManifest, typeId: string, value: unknown): string => {
-  const type = typeOf(manifest, typeId);
-  if (type.kind !== "enum") return formatScalar(value);
-  if (typeof value === "string" && Object.hasOwn(type.members, value)) return value;
-  if (typeof value !== "number") return formatScalar(value);
-  const member = Object.entries(type.members).find(([, number]) => number === value)?.[0];
-  return member ?? `${value} (not a ${type.name})`;
+export const formatValue = (
+	manifest: DebugManifest,
+	typeId: string,
+	value: unknown,
+): string => {
+	const type = typeOf(manifest, typeId);
+	if (type.kind !== "enum") {
+		return formatScalar(value);
+	}
+	if (typeof value === "string" && Object.hasOwn(type.members, value)) {
+		return value;
+	}
+	if (typeof value !== "number") {
+		return formatScalar(value);
+	}
+	const member = Object.entries(type.members).find(
+		([, number]) => number === value,
+	)?.[0];
+	return member ?? `${value} (not a ${type.name})`;
 };
 
 export const typeLabel = (manifest: DebugManifest, typeId: string): string => {
-  const type = typeOf(manifest, typeId);
-  switch (type.kind) {
-    case "scalar":
-      return type.iec;
-    case "enum":
-    case "record":
-      return type.name;
-    case "array":
-      return `${typeLabel(manifest, type.element)}[${type.length}]`;
-  }
+	const type = typeOf(manifest, typeId);
+	switch (type.kind) {
+		case "scalar":
+			return type.iec;
+		case "enum":
+		case "record":
+			return type.name;
+		case "array":
+			return `${typeLabel(manifest, type.element)}[${type.length}]`;
+	}
 };
 
 const PROPERTY_TEXT = 16;
 
 /** A record's properties as `barcode=CON-MD3-884… scanner=3`, long strings cut short. */
 export const formatProperties = (properties: Record<string, unknown>) =>
-  Object.entries(properties)
-    .map(([key, value]) => {
-      const text = typeof value === "string" ? value : formatScalar(value);
-      return `${key}=${text.length > PROPERTY_TEXT ? `${text.slice(0, PROPERTY_TEXT)}…` : text}`;
-    })
-    .join(" ");
+	Object.entries(properties)
+		.map(([key, value]) => {
+			const text = typeof value === "string" ? value : formatScalar(value);
+			return `${key}=${text.length > PROPERTY_TEXT ? `${text.slice(0, PROPERTY_TEXT)}…` : text}`;
+		})
+		.join(" ");
 
 /** A VS Code link to a project file, when the project root on the debugger host is known. */
-const fileHref = (projectRoot: string | undefined, file: string, line: number, column: number) => {
-  if (projectRoot === undefined) return undefined;
-  const root = projectRoot.replaceAll("\\", "/").replace(/\/$/, "");
-  const absolute = `${root}/${file}`.replace(/^\/?/, "/");
-  return `vscode://file${absolute}:${line}:${column}`;
+const fileHref = (
+	projectRoot: string | undefined,
+	file: string,
+	line: number,
+	column: number,
+) => {
+	if (projectRoot === undefined) {
+		return undefined;
+	}
+	const root = projectRoot.replaceAll("\\", "/").replace(/\/$/, "");
+	const absolute = `${root}/${file}`.replace(/^\/?/, "/");
+	return `vscode://file${absolute}:${line}:${column}`;
 };
 
 /** `file:line`, and a VS Code link when the project root on the debugger host is known. */
 export const sourceLocation = (
-  manifest: DebugManifest,
-  projectRoot: string | undefined,
-  range: SourceRange,
+	manifest: DebugManifest,
+	projectRoot: string | undefined,
+	range: SourceRange,
 ) => {
-  const file = manifest.sources[range.file] ?? `source ${range.file}`;
-  const href = fileHref(projectRoot, file, range.line, range.column);
-  return { label: `${file}:${range.line}`, ...(href && { href }) };
+	const file = manifest.sources[range.file] ?? `source ${range.file}`;
+	const href = fileHref(projectRoot, file, range.line, range.column);
+	return { label: `${file}:${range.line}`, ...(href && { href }) };
 };
 
 /** A record's project-relative `file:line` as `basename:line`, with the same VS Code link. */
-export const recordLocation = (projectRoot: string | undefined, source: string) => {
-  const [, file = source, line] = /^(.*):(\d+)$/.exec(source) ?? [];
-  const label = `${file.slice(file.lastIndexOf("/") + 1)}${line ? `:${line}` : ""}`;
-  const href = line === undefined ? undefined : fileHref(projectRoot, file, Number(line), 1);
-  return { label, ...(href && { href }) };
+export const recordLocation = (
+	projectRoot: string | undefined,
+	source: string,
+) => {
+	const [, file = source, line] = /^(.*):(\d+)$/.exec(source) ?? [];
+	const label = `${file.slice(file.lastIndexOf("/") + 1)}${line ? `:${line}` : ""}`;
+	const href =
+		line === undefined
+			? undefined
+			: fileHref(projectRoot, file, Number(line), 1);
+	return { label, ...(href && { href }) };
 };