@cssints/apg-specs 0.0.0-stage → 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @cssints/apg-specs — APG widget specs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Quint specs behind [`@cssints/headless`](../headless/README.md): one spec per WAI-ARIA APG pattern (plus the canvas camera/pointer contract), the generated models and typed scaffolding, the `SpecBridge` for each pattern, the ported upstream scenario sets, and the spec-only verification. It is the test oracle of the widgets and of `native/headless`, and it is published so that widget libraries outside this repository can replay the same specs and scenarios against their own code.
+
+The generated files (`*.model.generated.json`, `*.scaffolding.generated.ts`) are written by the code generation of [`@quint-machine/core`](https://www.npmjs.com/package/@quint-machine/core) and are never edited by hand. Ticket ids like `effects-of-atmosphere-dx00` in the comments of the specs and tests are tickets of the repository these files came from.
+
+## Layout
+
+```
+specs/apg/<pattern>.qnt                           # APG pattern specs (one behavior-machine each)
+specs/canvas/<machine>.qnt                        # canvas camera + pointer specs
+shared/<module>.qnt                               # vocabulary + pure defs: aria, focusgroup, popover, invokers, details-group
+src/<service>/<machine>.model.generated.json      # generated model document
+src/<service>/<machine>.scaffolding.generated.ts  # generated typed scaffolding
+src/apg/<pattern>.bridge.ts                       # scenario vocabulary <-> spec events/state
+src/scenario.ts                                   # scenario decoder + replay/differential-walk runtime
+scenarios/apg/*.json, scenarios/canvas/*.json     # ported upstream scenario sets
+scenarios/parts.json                              # part names per pattern
+test/<service>/<machine>.test.ts                  # spec-only verification
+scripts/generate-all.ts                           # regenerates every spec under specs/
+```
+
+Platform-contract modules (`shared/focusgroup.qnt` roving tabindex, `shared/popover.qnt` light dismiss, `shared/invokers.qnt` `commandfor`/`command`, `shared/details-group.qnt` `<details name>`) are one per native web feature; a pattern imports one and models only its delta. `shared/` holds vocabulary and pure defs only.
+
+## Commands
+
+Run in `packages/apg-specs`:
+
+- `bun run generate:all [specs/apg/tabs.qnt ...]` — regenerate artifacts (`node scripts/generate-all.ts`). Each generated file carries the sha256 of its spec; edit a spec, then regenerate. The formatter skips the generated files (`.prettierignore`).
+- `bun run typecheck:quint` — Quint's own typechecker over every spec (~90 s).
+- `bun run test` — spec-only verification (`vp test run`). The exhaustive explorations (player, camera) take a minute each and can time out on a loaded machine; run them alone before calling a failure real.
+- `bun run typecheck` — `tsc-rs` over `src`, `test` and `scripts`.
+- `bun run check` — all of the above, in order.
+
+- `bun run build` — `vp pack`: `dist/` (the runner and the bridges as ESM with `.d.mts`, the generated models as `.json`).
+
+## Install and use
+
+```sh
+npm install @cssints/apg-specs effect @quint-machine/core
+```
+
+`effect` (`^4.0.0`) is a peer, `@quint-machine/core` a dependency. The package has subpath exports only:
+
+| Specifier                                                                        | What                                                                                                             |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `@cssints/apg-specs/scenario`                                                    | the scenario decoder, `replayScenario`, `differentialWalk`, `specDriver`, `Unsupported`, driver and bridge types |
+| `@cssints/apg-specs/apg/<pattern>.bridge`                                        | the `SpecBridge`, `<pattern>Config`, `<pattern>Steps` and `<pattern>Probe` of a pattern                          |
+| `@cssints/apg-specs/apg/<pattern>.model.json`                                    | the generated model document (`src/apg/<pattern>.model.generated.json` in the repository)                        |
+| `@cssints/apg-specs/canvas/{canvas.bridge,camera.model.json,pointer.model.json}` | the canvas bridge and models                                                                                     |
+| `@cssints/apg-specs/scenarios/apg/<pattern>.<set>.json`                          | a ported scenario set (also `scenarios/canvas/*.json`, `scenarios/parts.json`)                                   |
+| `@cssints/apg-specs/specs/apg/<pattern>.qnt`                                     | the raw Quint spec (also `specs/canvas/*.qnt`, `shared/*.qnt`, which the specs import)                           |
+
+```ts
+import {
+  Unsupported,
+  differentialWalk,
+  replayScenario,
+  specDriver,
+} from "@cssints/apg-specs/scenario";
+import { buttonBridge, buttonConfig } from "@cssints/apg-specs/apg/button.bridge";
+import buttonModel from "@cssints/apg-specs/apg/button.model.json" with { type: "json" };
+import baseUi from "@cssints/apg-specs/scenarios/apg/button.base-ui.json" with { type: "json" };
+```
+
+In this repository the `development` (vite, tsc) and `bun` export conditions point at `src/`. The scenario format is specified in `scenarios/apg/README.md`.

package/dist/apg/accordion.bridge.d.mts

@@ -0,0 +1,35 @@
+import { ActionStep, Probe, ScenarioConfig, SpecBridge } from "../scenario.mjs";
+//#region src/apg/accordion.bridge.d.ts
+export interface AccordionConfig {
+  readonly items: number;
+  /** `defaultValue` when uncontrolled, the initial `value` prop when controlled. */
+  readonly expanded: ReadonlyArray<boolean>;
+  readonly multiple: boolean;
+  readonly collapsible: boolean;
+  readonly controlled: boolean;
+  /** Controlled only: the host writes every request's intent back as the value. */
+  readonly accepts: boolean;
+}
+/**
+ * Scenario `config` -> what both targets are mounted with. `expanded` is the
+ * controlled value (a host that rejects every request, like react-aria's
+ * `isExpanded`); `controlled` alone is a host that accepts every request;
+ * `accepts` overrides. `defaultExpanded` is the initial value either way. The
+ * spec models a fixed three-panel accordion, per-panel disabled, item values,
+ * custom ids and the keep-mounted / hidden-until-found flags are not modelled
+ * and make the scenario `Unsupported` (skipped, never silently replayed).
+ */
+export declare const accordionConfig: (config: ScenarioConfig) => AccordionConfig;
+/**
+ * Accordion vocabulary <-> `specs/apg/accordion.qnt`, shared by the spec driver
+ * and the DOM driver so both gate scenarios identically.
+ *
+ * The spec has no "focus this header" event (`focus` is a Tab-driven slot), so
+ * a `focus` step is a no-op here and activation is driven by the step's target
+ * (`click_header`), which sets the same slot a real click would.
+ */
+export declare const accordionBridge: SpecBridge;
+/** The user-level steps a differential walk draws from. */
+export declare const accordionSteps: ReadonlyArray<ActionStep>;
+export declare const accordionProbe: Probe;
+//#endregion

package/dist/apg/accordion.bridge.mjs

@@ -0,0 +1,326 @@
+import { Unsupported } from "../scenario.mjs";
+//#region src/apg/accordion.bridge.ts
+const specEvent = (tag, params = {}) => ({
+	_tag: tag,
+	...params
+});
+/** The generator models a fixed three-panel accordion (no collection state). */
+const PANELS = 3;
+/**
+* Scenario parts -> the spec's names: `trigger` <- `header`, `panel` <- `content`;
+* `heading` is the static wrapper. Anything else (groups, menus, ...) is
+* `Unsupported`, which skips the scenario on every target.
+*/
+const partOf = (target) => {
+	const [name = "", indexText] = (target ?? "trigger").split(":");
+	const index = Number(indexText ?? "0");
+	if (name === "trigger" || name === "header" || name === "button") return {
+		kind: "trigger",
+		index
+	};
+	if (name === "panel" || name === "content") return {
+		kind: "panel",
+		index
+	};
+	if (name === "heading") return {
+		kind: "heading",
+		index
+	};
+	throw new Unsupported(`part ${name}`);
+};
+const b2i = (value) => value ? 1 : 0;
+/** Bit 0 = panel 0, bit 1 = panel 1, bit 2 = panel 2. */
+const packed = (expanded) => b2i(expanded[0] === true) + 2 * b2i(expanded[1] === true) + 4 * b2i(expanded[2] === true);
+const expandedIndicesOfPacked = (packedValue) => [
+	0,
+	1,
+	2
+].filter((index) => Math.floor(packedValue / 2 ** index) % 2 === 1);
+/** Resolve one `expanded` entry (an index or a boolean) to a panel index. */
+const indexOf = (entry, items) => {
+	if (typeof entry === "number" && Number.isInteger(entry)) {
+		if (entry < 0 || entry >= items) throw new Unsupported(`expanded index ${entry}`);
+		return entry;
+	}
+	throw new Unsupported(`expanded entry ${JSON.stringify(entry)}`);
+};
+/**
+* Scenario `config` -> what both targets are mounted with. `expanded` is the
+* controlled value (a host that rejects every request, like react-aria's
+* `isExpanded`); `controlled` alone is a host that accepts every request;
+* `accepts` overrides. `defaultExpanded` is the initial value either way. The
+* spec models a fixed three-panel accordion, per-panel disabled, item values,
+* custom ids and the keep-mounted / hidden-until-found flags are not modelled
+* and make the scenario `Unsupported` (skipped, never silently replayed).
+*/
+const accordionConfig = (config) => {
+	let items = PANELS;
+	let multiple = false;
+	let collapsible = true;
+	let controlled = false;
+	let accepts = false;
+	const expanded = [
+		false,
+		false,
+		false
+	];
+	for (const [key, value] of Object.entries(config)) if (key === "items") {
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > PANELS) throw new Unsupported(`config items=${JSON.stringify(value)}`);
+		items = value;
+	} else if (key === "defaultExpanded") {
+		if (!Array.isArray(value)) throw new Unsupported(`config defaultExpanded=${JSON.stringify(value)}`);
+		for (const entry of value) expanded[indexOf(entry, items)] = true;
+	} else if (key === "expanded") {
+		controlled = true;
+		if (typeof value === "boolean") expanded[0] = value;
+		else if (Array.isArray(value)) for (const entry of value) expanded[indexOf(entry, items)] = true;
+		else throw new Unsupported(`config expanded=${JSON.stringify(value)}`);
+	} else if (key === "controlled") {
+		if (typeof value !== "boolean") throw new Unsupported(`config controlled=${JSON.stringify(value)}`);
+		controlled = value;
+		accepts = value;
+	} else if (key === "accepts") {
+		if (typeof value !== "boolean") throw new Unsupported(`config accepts=${JSON.stringify(value)}`);
+		controlled = true;
+		accepts = value;
+	} else if (key === "multiple") {
+		if (typeof value !== "boolean") throw new Unsupported(`config multiple=${JSON.stringify(value)}`);
+		multiple = value;
+	} else if (key === "collapsible") {
+		if (typeof value !== "boolean") throw new Unsupported(`config collapsible=${JSON.stringify(value)}`);
+		collapsible = value;
+	} else throw new Unsupported(`config ${key}=${JSON.stringify(value)}`);
+	return {
+		items,
+		expanded,
+		multiple,
+		collapsible,
+		controlled,
+		accepts
+	};
+};
+const expandedCount = (state) => (state["expanded0"] === true ? 1 : 0) + (state["expanded1"] === true ? 1 : 0) + (state["expanded2"] === true ? 1 : 0);
+const expandedAt = (state, index) => state[`expanded${index}`] === true;
+const canCollapse = (state) => state["collapsible"] === true || expandedCount(state) >= 2;
+const expandedIndices = (state) => [
+	0,
+	1,
+	2
+].filter((index) => expandedAt(state, index));
+const indicesFrom = (value) => {
+	if (typeof value === "boolean") return [
+		value,
+		false,
+		false
+	];
+	if (!Array.isArray(value)) throw new Unsupported(`expanded value=${JSON.stringify(value)}`);
+	const expanded = [
+		false,
+		false,
+		false
+	];
+	for (const entry of value) expanded[indexOf(entry, PANELS)] = true;
+	return expanded;
+};
+const programmatic = (step) => {
+	switch (step.prop) {
+		case "multiple": return [specEvent("set_multiple", { allow: step.value === true })];
+		case "collapsible": return [specEvent("set_collapsible", { allow: step.value === true })];
+		case "headingLevel": {
+			const level = typeof step.value === "number" ? step.value : 0;
+			if (!Number.isInteger(level) || level < 1 || level > 6) throw new Unsupported(`headingLevel ${JSON.stringify(step.value)}`);
+			return [specEvent("set_heading_level", { level: BigInt(level) })];
+		}
+		case "expanded":
+		case "setValue": return [specEvent("setValue", { v: BigInt(packed(indicesFrom(step.value))) })];
+		case "hostToggle": return [specEvent("hostToggle", { panel: BigInt(0) })];
+		default: throw new Unsupported(`prop ${step.prop ?? ""}`);
+	}
+};
+/**
+* Accordion vocabulary <-> `specs/apg/accordion.qnt`, shared by the spec driver
+* and the DOM driver so both gate scenarios identically.
+*
+* The spec has no "focus this header" event (`focus` is a Tab-driven slot), so
+* a `focus` step is a no-op here and activation is driven by the step's target
+* (`click_header`), which sets the same slot a real click would.
+*/
+const accordionBridge = {
+	setup: (config) => {
+		const { expanded, multiple, collapsible, controlled, accepts } = accordionConfig(config);
+		const events = [];
+		if (multiple) events.push(specEvent("set_multiple", { allow: true }));
+		if (!collapsible) events.push(specEvent("set_collapsible", { allow: false }));
+		if (controlled) {
+			events.push(specEvent("control"));
+			if (accepts) events.push(specEvent("acceptRequests"));
+			if (expanded.some(Boolean)) events.push(specEvent("setValue", { v: BigInt(packed(expanded)) }));
+		} else for (const index of [
+			2,
+			1,
+			0
+		]) if (expanded[index] === true) events.push(specEvent("click_header", { panel: BigInt(index) }));
+		if (events.length > 0) events.push(specEvent("blur"));
+		return events;
+	},
+	event: (step) => {
+		switch (step.event) {
+			case "focus": return [];
+			case "blur":
+				partOf(step.target);
+				return [specEvent("blur")];
+			case "click": {
+				const { kind, index } = partOf(step.target);
+				if (kind === "trigger") return [specEvent("click_header", { panel: BigInt(index) })];
+				if (kind === "panel") return [specEvent("click_content", { panel: BigInt(index) })];
+				throw new Unsupported(`click on ${step.target ?? ""}`);
+			}
+			case "key": {
+				const { kind, index } = partOf(step.target);
+				if (kind === "trigger" && (step.key === "Enter" || step.key === " " || step.key === "Space")) return [specEvent("click_header", { panel: BigInt(index) })];
+				throw new Unsupported(`key ${step.key ?? ""} on ${step.target ?? ""}`);
+			}
+			case "hover":
+			case "unhover": return [];
+			case "prop": return programmatic(step);
+			default: throw new Unsupported(`event ${step.event}`);
+		}
+	},
+	value: (state) => ({ expanded: expandedIndices(state) }),
+	focus: (state) => {
+		const slot = Number(state["focus"]);
+		if (slot < 0) return null;
+		return slot % 2 === 0 ? `trigger:${slot / 2}` : `panel:${(slot - 1) / 2}`;
+	},
+	attr: (state, target, name) => {
+		const { kind, index } = partOf(target);
+		if (kind === "trigger") {
+			if (name === "aria-expanded") return expandedAt(state, index) ? "true" : "false";
+			if (name === "aria-controls") return `panel:${index}`;
+			if (name === "aria-disabled") return expandedAt(state, index) && !canCollapse(state) ? "true" : null;
+		} else if (kind === "panel") {
+			if (name === "hidden") return expandedAt(state, index) ? null : "true";
+			if (name === "role") return "region";
+			if (name === "aria-labelledby") return `trigger:${index}`;
+		} else if (kind === "heading") {
+			if (name === "role") return "heading";
+			if (name === "aria-level") return String(state["headingLevel"]);
+		}
+		throw new Unsupported(`attribute ${name} on ${target}`);
+	},
+	visible: (state) => [
+		0,
+		1,
+		2
+	].flatMap((index) => expandedAt(state, index) ? [`panel:${index}`] : []),
+	events: (before, after) => before["requests"] === after["requests"] ? [] : [["onExpandedChange", expandedIndicesOfPacked(Number(after["requested"]))]]
+};
+/** The user-level steps a differential walk draws from. */
+const accordionSteps = [
+	{
+		event: "click",
+		target: "trigger:0"
+	},
+	{
+		event: "click",
+		target: "trigger:1"
+	},
+	{
+		event: "click",
+		target: "trigger:2"
+	},
+	{
+		event: "key",
+		key: "Enter",
+		target: "trigger:0"
+	},
+	{
+		event: "key",
+		key: "Enter",
+		target: "trigger:1"
+	},
+	{
+		event: "key",
+		key: "Enter",
+		target: "trigger:2"
+	},
+	{
+		event: "key",
+		key: " ",
+		target: "trigger:0"
+	},
+	{
+		event: "key",
+		key: " ",
+		target: "trigger:1"
+	},
+	{
+		event: "key",
+		key: " ",
+		target: "trigger:2"
+	},
+	{
+		event: "prop",
+		prop: "multiple",
+		value: true
+	},
+	{
+		event: "prop",
+		prop: "multiple",
+		value: false
+	},
+	{
+		event: "prop",
+		prop: "collapsible",
+		value: false
+	},
+	{
+		event: "prop",
+		prop: "collapsible",
+		value: true
+	},
+	{
+		event: "prop",
+		prop: "headingLevel",
+		value: 2
+	},
+	{
+		event: "prop",
+		prop: "headingLevel",
+		value: 4
+	},
+	{
+		event: "prop",
+		prop: "expanded",
+		value: [0]
+	},
+	{
+		event: "prop",
+		prop: "expanded",
+		value: [0, 1]
+	},
+	{
+		event: "prop",
+		prop: "expanded",
+		value: []
+	},
+	{
+		event: "prop",
+		prop: "hostToggle"
+	}
+];
+const accordionProbe = {
+	attrs: [
+		["trigger:0", "aria-expanded"],
+		["trigger:1", "aria-expanded"],
+		["trigger:2", "aria-expanded"],
+		["trigger:0", "aria-disabled"],
+		["trigger:1", "aria-disabled"],
+		["panel:0", "hidden"],
+		["panel:1", "hidden"],
+		["panel:2", "hidden"]
+	],
+	events: ["onExpandedChange"]
+};
+//#endregion
+export { accordionBridge, accordionConfig, accordionProbe, accordionSteps };