@cssints/apg-specs 0.0.0-stage → 0.5.1

package/dist/apg/listbox-shared.d.mts

@@ -0,0 +1,58 @@
+import { ScenarioConfig } from "../scenario.mjs";
+import { QuintEvent, QuintModelValue } from "@quint-machine/core";
+import { Schema } from "effect";
+//#region src/apg/listbox-shared.d.ts
+export declare const specEvent: (tag: string, params?: Record<string, bigint | string | boolean>) => QuintEvent;
+export type ListboxSelectionMode = "single" | "multiple" | "none";
+export type ListboxAutoFocus = boolean | number | "first";
+/**
+ * What every listbox fixture is mounted with. `items` are the option labels
+ * (the DOM's visible/typeahead text); the spec models are index-based, so the
+ * differential walk mounts the spec's option names as labels.
+ */
+export interface ListboxMountConfig {
+  readonly items: ReadonlyArray<string>;
+  readonly selectionMode: ListboxSelectionMode;
+  readonly followsFocus: boolean;
+  /** Option indices selected at mount (uncontrolled default / controlled initial). */
+  readonly defaultSelected: ReadonlyArray<number>;
+  /** Option indices that cannot be selected or focused by navigation. */
+  readonly disabled: ReadonlyArray<number>;
+  readonly focusOnHover: boolean;
+  readonly autoFocus: ListboxAutoFocus | undefined;
+  readonly ariaLabel: string | undefined;
+  /** The host owns the value: the fixture passes it as `value`. */
+  readonly controlled: boolean;
+  /** Controlled only: the host writes every request's intent back as the value. */
+  readonly accepts: boolean;
+  /** Uncontrolled active option at mount (the type-ahead model's value). */
+  readonly defaultActive: number | undefined;
+}
+/**
+ * Scenario `config` -> the fixture mount config, shared by every listbox
+ * bridge and every target. Unknown keys (triggers, popups, layouts, value
+ * plumbing, ...) throw `Unsupported`, which skips the scenario everywhere.
+ */
+export declare const listboxConfig: (config: ScenarioConfig, defaultMode?: ListboxSelectionMode) => ListboxMountConfig;
+/** `option:3`/`option` -> index; anything else is unsupported. */
+export declare const optionIndexOf: (target: string | undefined) => number;
+export declare const partOf: (target: string | undefined) => string;
+export declare const jsonRecord: (value: Schema.Json | undefined) => Readonly<Record<string, Schema.Json>>;
+export interface KeyModifiers {
+  readonly shift: boolean;
+  readonly ctrl: boolean;
+  readonly meta: boolean;
+  readonly alt: boolean;
+}
+export declare const keyModifiers: (value: Schema.Json | undefined) => KeyModifiers;
+/** bit i of a selection mask. */
+export declare const bit: (mask: bigint, index: number) => boolean;
+export declare const maskOf: (state: QuintModelValue) => bigint;
+export declare const selectedIndices: (mask: bigint, count: number) => ReadonlyArray<number>;
+/** Option indices -> a selection bitmask (bit i = option i). */
+export declare const indicesMask: (indices: ReadonlyArray<number>) => number;
+/** Parse a `prop setValue`/`value`/`selected` payload into option indices. */
+export declare const indicesOf: (value: Schema.Json | undefined) => ReadonlyArray<number>;
+/** The last request's intent, as option indices (reads the `requested` mask). */
+export declare const requestedIndices: (state: QuintModelValue, count: number) => ReadonlyArray<number>;
+//#endregion

package/dist/apg/listbox-shared.mjs

@@ -0,0 +1,171 @@
+import { Unsupported } from "../scenario.mjs";
+//#region src/apg/listbox-shared.ts
+const specEvent = (tag, params = {}) => ({
+	_tag: tag,
+	...params
+});
+const toItems = (value) => {
+	if (typeof value === "number") {
+		if (!Number.isInteger(value) || value < 0) throw new Unsupported(`items ${String(value)}`);
+		return Array.from({ length: value }, (_, i) => String(i));
+	}
+	if (Array.isArray(value) && value.every((v) => typeof v === "string")) return value;
+	throw new Unsupported(`items ${JSON.stringify(value)}`);
+};
+const indexOfLabel = (items, key) => {
+	const exact = items.indexOf(key);
+	if (exact >= 0) return exact;
+	const lower = key.toLowerCase();
+	const folded = items.findIndex((item) => item.toLowerCase() === lower);
+	if (folded < 0) throw new Unsupported(`key ${key}`);
+	return folded;
+};
+const numberArray = (value) => {
+	if (Array.isArray(value) && value.every((v) => typeof v === "number" && Number.isInteger(v))) return value;
+	throw new Unsupported(`indices ${JSON.stringify(value)}`);
+};
+const keyIndices = (items, value) => {
+	if (Array.isArray(value) && value.every((v) => typeof v === "string")) return value.map((key) => indexOfLabel(items, key));
+	throw new Unsupported(`keys ${JSON.stringify(value)}`);
+};
+const MODES = /* @__PURE__ */ new Set([
+	"single",
+	"multiple",
+	"none"
+]);
+/**
+* Scenario `config` -> the fixture mount config, shared by every listbox
+* bridge and every target. Unknown keys (triggers, popups, layouts, value
+* plumbing, ...) throw `Unsupported`, which skips the scenario everywhere.
+*/
+const listboxConfig = (config, defaultMode = "single") => {
+	let items = [];
+	let selectionMode = defaultMode;
+	let followsFocus = false;
+	let defaultSelected = [];
+	let disabled = [];
+	let focusOnHover = false;
+	let autoFocus;
+	let ariaLabel;
+	let controlled = false;
+	let accepts = false;
+	let defaultActive;
+	for (const [key, value] of Object.entries(config)) switch (key) {
+		case "items":
+			items = toItems(value);
+			break;
+		case "selectionMode":
+			if (typeof value !== "string" || !MODES.has(value)) throw new Unsupported(`selectionMode ${JSON.stringify(value)}`);
+			selectionMode = value;
+			break;
+		case "selectionModel":
+			if (value !== "recommended") throw new Unsupported(`selectionModel ${JSON.stringify(value)}`);
+			break;
+		case "followsFocus":
+			followsFocus = value === true;
+			break;
+		case "defaultSelectedKeys":
+			defaultSelected = keyIndices(items, value);
+			break;
+		case "defaultSelected":
+			defaultSelected = numberArray(value);
+			break;
+		case "value":
+		case "selected":
+			defaultSelected = numberArray(value);
+			controlled = true;
+			break;
+		case "controlled":
+			if (typeof value !== "boolean") throw new Unsupported(`controlled ${JSON.stringify(value)}`);
+			controlled = value;
+			accepts = value;
+			break;
+		case "accepts":
+			if (typeof value !== "boolean") throw new Unsupported(`accepts ${JSON.stringify(value)}`);
+			controlled = true;
+			accepts = value;
+			break;
+		case "defaultActive":
+			if (typeof value !== "number" || !Number.isInteger(value)) throw new Unsupported(`defaultActive ${JSON.stringify(value)}`);
+			defaultActive = value;
+			break;
+		case "disabledKeys":
+			disabled = keyIndices(items, value);
+			break;
+		case "disabled":
+			disabled = numberArray(value);
+			break;
+		case "shouldFocusOnHover":
+			focusOnHover = value === true;
+			break;
+		case "autoFocus":
+			if (value === true || value === "first" || typeof value === "number" && Number.isInteger(value)) autoFocus = value;
+			else if (value === false) autoFocus = void 0;
+			else throw new Unsupported(`autoFocus ${JSON.stringify(value)}`);
+			break;
+		case "ariaLabel":
+			if (typeof value !== "string") throw new Unsupported(`ariaLabel ${JSON.stringify(value)}`);
+			ariaLabel = value;
+			break;
+		default: throw new Unsupported(`config ${key}=${JSON.stringify(value)}`);
+	}
+	if (items.length === 0) throw new Unsupported("config has no items");
+	return {
+		items,
+		selectionMode,
+		followsFocus,
+		defaultSelected,
+		disabled,
+		focusOnHover,
+		autoFocus,
+		ariaLabel,
+		controlled,
+		accepts,
+		defaultActive
+	};
+};
+/** `option:3`/`option` -> index; anything else is unsupported. */
+const optionIndexOf = (target) => {
+	const part = (target ?? "option").replace(/:0$/, "");
+	if (part === "option") return 0;
+	const match = /^option:(\d+)$/.exec(part);
+	if (match?.[1] === void 0) throw new Unsupported(`target ${target ?? ""}`);
+	return Number(match[1]);
+};
+const partOf = (target) => (target ?? "").replace(/:0$/, "");
+const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const jsonRecord = (value) => {
+	if (value === void 0 || !isJsonObject(value)) throw new Unsupported(`value ${JSON.stringify(value)}`);
+	return value;
+};
+const keyModifiers = (value) => {
+	const record = jsonRecord(value);
+	return {
+		shift: record["shift"] === true,
+		ctrl: record["ctrl"] === true,
+		meta: record["meta"] === true || record["ctrl"] === true,
+		alt: record["alt"] === true
+	};
+};
+/** bit i of a selection mask. */
+const bit = (mask, index) => (mask >> BigInt(index)) % 2n === 1n;
+const maskOf = (state) => {
+	const value = state["selected"];
+	return typeof value === "bigint" ? value : 0n;
+};
+const selectedIndices = (mask, count) => {
+	const out = [];
+	for (let i = 0; i < count; i += 1) if (bit(mask, i)) out.push(i);
+	return out;
+};
+/** Option indices -> a selection bitmask (bit i = option i). */
+const indicesMask = (indices) => indices.reduce((mask, index) => mask + 2 ** index, 0);
+/** Parse a `prop setValue`/`value`/`selected` payload into option indices. */
+const indicesOf = (value) => numberArray(value);
+/** The last request's intent, as option indices (reads the `requested` mask). */
+const requestedIndices = (state, count) => {
+	const value = state["requested"];
+	return selectedIndices(typeof value === "bigint" ? value : 0n, count);
+};
+//#endregion
+export { bit, indicesMask, indicesOf, jsonRecord, keyModifiers, listboxConfig, maskOf, optionIndexOf, partOf, requestedIndices, selectedIndices, specEvent };

package/dist/apg/listbox-single.bridge.d.mts

@@ -0,0 +1,10 @@
+import { ActionStep, Probe, ScenarioConfig, SpecBridge } from "../scenario.mjs";
+import { ListboxMountConfig } from "./listbox-shared.mjs";
+//#region src/apg/listbox-single.bridge.d.ts
+/** Scenario `config` -> mount config; only the single-select model is modelled. */
+export declare const listboxSingleConfig: (config: ScenarioConfig) => ListboxMountConfig;
+export declare const listboxSingleBridge: SpecBridge;
+/** The user-level steps a differential walk draws from. */
+export declare const listboxSingleSteps: ReadonlyArray<ActionStep>;
+export declare const listboxSingleProbe: Probe;
+//#endregion

package/dist/apg/listbox-single.bridge.mjs

@@ -0,0 +1,196 @@
+import { Unsupported } from "../scenario.mjs";
+import { bit, indicesMask, indicesOf, jsonRecord, listboxConfig, maskOf, optionIndexOf, partOf, requestedIndices, specEvent } from "./listbox-shared.mjs";
+//#region src/apg/listbox-single.bridge.ts
+/** Scenario `config` -> mount config; only the single-select model is modelled. */
+const listboxSingleConfig = (config) => {
+	const mount = listboxConfig(config, "single");
+	if (mount.selectionMode !== "single") throw new Unsupported(`selectionMode ${mount.selectionMode}`);
+	return mount;
+};
+/**
+* Listbox (single-select) vocabulary <-> `specs/apg/listbox-single.qnt`.
+* Parts: `listbox` (the focus holder / tab stop) and `option:N`. The primitive
+* keeps DOM focus on the active option, so `focus` is the active option's
+* target; `listbox[aria-activedescendant]` cross-checks it.
+*
+* Config the spec does not model (triggers/popups, `open`, `defaultValue`,
+* layouts) throws `Unsupported`, skipping the scenario on every target.
+*/
+const keyEvents = (key) => {
+	switch (key) {
+		case "ArrowDown": return [specEvent("arrow_down")];
+		case "ArrowUp": return [specEvent("arrow_up")];
+		case "Home": return [specEvent("home")];
+		case "End": return [specEvent("end")];
+		case " ":
+		case "Space":
+		case "Enter": return [specEvent("space")];
+		default: throw new Unsupported(`key ${key}`);
+	}
+};
+const propEvents = (step) => {
+	switch (step.prop) {
+		case "focus": return [specEvent("focus_in")];
+		case "blur": return [specEvent("blur")];
+		case "followsFocus":
+		case "set_follows_focus": return [specEvent("set_follows_focus", { follow: step.value === true })];
+		case "setValue":
+		case "value":
+		case "selected": return [specEvent("setValue", { v: BigInt(indicesMask(indicesOf(step.value))) })];
+		case "hostToggle": return [specEvent("hostToggle", { panel: 0n })];
+		case "key": {
+			const key = jsonRecord(step.value)["key"];
+			if (typeof key !== "string") throw new Unsupported(`prop key ${JSON.stringify(step.value)}`);
+			return keyEvents(key);
+		}
+		default: throw new Unsupported(`prop ${step.prop ?? ""}`);
+	}
+};
+const listboxSingleBridge = {
+	setup: (config) => {
+		const mount = listboxSingleConfig(config);
+		const events = [];
+		if (mount.followsFocus) events.push(specEvent("set_follows_focus", { follow: true }));
+		if (mount.controlled) {
+			events.push(specEvent("control"));
+			if (mount.accepts) events.push(specEvent("acceptRequests"));
+			if (mount.defaultSelected.length > 0) events.push(specEvent("setValue", { v: BigInt(indicesMask(mount.defaultSelected)) }));
+		} else events.push(specEvent("seed", { index: BigInt(mount.defaultSelected[0] ?? 6) }));
+		return events;
+	},
+	event: (step) => {
+		switch (step.event) {
+			case "focus": return [specEvent("focus_in")];
+			case "blur": return [specEvent("blur")];
+			case "click": return [specEvent("click", { index: BigInt(optionIndexOf(step.target)) })];
+			case "key": return keyEvents(step.key ?? "");
+			case "hover":
+			case "unhover": return [];
+			case "prop": return propEvents(step);
+			default: throw new Unsupported(`event ${step.event}`);
+		}
+	},
+	focus: (state) => state["hasFocus"] === true ? `option:${state["active"]}` : null,
+	attr: (state, target, name) => {
+		const part = partOf(target);
+		if (part === "listbox") {
+			if (name === "aria-multiselectable") return "false";
+			if (name === "aria-activedescendant") return state["hasFocus"] === true ? `option:${state["active"]}` : null;
+		} else if (part.startsWith("option")) {
+			if (name === "aria-selected") return bit(maskOf(state), optionIndexOf(target)) ? "true" : "false";
+			if (name === "aria-disabled") return null;
+		}
+		throw new Unsupported(`attribute ${name} on ${target}`);
+	},
+	visible: () => [],
+	events: (before, after) => before["requests"] === after["requests"] ? [] : [["onValueChange", requestedIndices(after, 6).map((index) => String(index))]]
+};
+/** The user-level steps a differential walk draws from. */
+const listboxSingleSteps = [
+	{
+		event: "prop",
+		prop: "focus"
+	},
+	{
+		event: "prop",
+		prop: "blur"
+	},
+	{
+		event: "prop",
+		prop: "key",
+		value: { key: "ArrowDown" }
+	},
+	{
+		event: "prop",
+		prop: "key",
+		value: { key: "ArrowUp" }
+	},
+	{
+		event: "prop",
+		prop: "key",
+		value: { key: "Home" }
+	},
+	{
+		event: "prop",
+		prop: "key",
+		value: { key: "End" }
+	},
+	{
+		event: "prop",
+		prop: "key",
+		value: { key: " " }
+	},
+	{
+		event: "prop",
+		prop: "key",
+		value: { key: "Enter" }
+	},
+	{
+		event: "prop",
+		prop: "followsFocus",
+		value: true
+	},
+	{
+		event: "prop",
+		prop: "followsFocus",
+		value: false
+	},
+	{
+		event: "prop",
+		prop: "setValue",
+		value: [0]
+	},
+	{
+		event: "prop",
+		prop: "setValue",
+		value: [3]
+	},
+	{
+		event: "prop",
+		prop: "setValue",
+		value: []
+	},
+	{
+		event: "prop",
+		prop: "hostToggle"
+	},
+	{
+		event: "click",
+		target: "option:0"
+	},
+	{
+		event: "click",
+		target: "option:1"
+	},
+	{
+		event: "click",
+		target: "option:2"
+	},
+	{
+		event: "click",
+		target: "option:3"
+	},
+	{
+		event: "click",
+		target: "option:4"
+	},
+	{
+		event: "click",
+		target: "option:5"
+	}
+];
+const listboxSingleProbe = {
+	attrs: [
+		["listbox", "aria-multiselectable"],
+		["listbox", "aria-activedescendant"],
+		["option:0", "aria-selected"],
+		["option:1", "aria-selected"],
+		["option:2", "aria-selected"],
+		["option:3", "aria-selected"],
+		["option:4", "aria-selected"],
+		["option:5", "aria-selected"]
+	],
+	events: ["onValueChange"]
+};
+//#endregion
+export { listboxSingleBridge, listboxSingleConfig, listboxSingleProbe, listboxSingleSteps };