@cssints/apg-specs 0.5.2 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @cssints/apg-specs — APG widget specs
 
-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 Quint specs behind [`@cssints/headless`](../headless/README.md): one spec per WAI-ARIA APG pattern, one per non-APG pattern composed of them (resizable panels), plus the canvas camera/pointer contract; the generated models and typed scaffolding, the `SpecBridge` for each pattern, the scenario sets (ported upstream ones and our own), 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.
 
@@ -9,12 +9,15 @@ The generated files (`*.model.generated.json`, `*.scaffolding.generated.ts`) are
 ```
 specs/apg/<pattern>.qnt                           # APG pattern specs (one behavior-machine each)
 specs/canvas/<machine>.qnt                        # canvas camera + pointer specs
+specs/patterns/<machine>.qnt                      # non-APG patterns composed of APG widgets (resizable-panels)
 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/patterns/<machine>.bridge.ts                  # the same, for a non-APG pattern
 src/scenario.ts                                   # scenario decoder + replay/differential-walk runtime
 scenarios/apg/*.json, scenarios/canvas/*.json     # ported upstream scenario sets
+scenarios/patterns/*.json                         # scenarios written from our own pattern specs
 scenarios/parts.json                              # part names per pattern
 test/<service>/<machine>.test.ts                  # spec-only verification
 scripts/generate-all.ts                           # regenerates every spec under specs/
@@ -31,7 +34,6 @@ Run in `packages/apg-specs`:
 - `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
@@ -47,9 +49,12 @@ npm install @cssints/apg-specs effect @quint-machine/core
 | `@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/patterns/<machine>.bridge`                                   | the same for a non-APG pattern composed of APG widgets (`resizable-panels`)                                      |
+| `@cssints/apg-specs/patterns/<machine>.model.json`                               | its generated model document (`src/patterns/<machine>.model.generated.json`)                                     |
 | `@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)                           |
+| `@cssints/apg-specs/scenarios/patterns/<machine>.spec.json`                      | a scenario set written from our own pattern spec                                                                 |
+| `@cssints/apg-specs/specs/apg/<pattern>.qnt`                                     | the raw Quint spec (also `specs/canvas/*.qnt`, `specs/patterns/*.qnt`, `shared/*.qnt`, which the specs import)   |
 
 ```ts
 import {
@@ -63,4 +68,4 @@ import buttonModel from "@cssints/apg-specs/apg/button.model.json" with { type:
 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`.
+In this repository the `development` (vite, tsc) and `bun` export conditions point at `src/`. The scenario format is specified in `scenarios/apg/README.md`; `scenarios/patterns/` holds the scenarios of our own non-APG patterns (same format, no upstream).

package/dist/patterns/resizable-panels.bridge.d.mts

@@ -0,0 +1,44 @@
+import { ActionStep, Probe, ScenarioConfig, SpecBridge } from "../scenario.mjs";
+//#region src/patterns/resizable-panels.bridge.d.ts
+export type PanelsOrientation = "vertical" | "horizontal";
+/** The layouts the spec reaches by a host write (hostEqual / hostWide / ...). */
+export declare const PANELS_LAYOUTS: {
+  readonly initial: readonly [20, 40, 40];
+  readonly equal: readonly [30, 30, 40];
+  readonly wide: readonly [50, 30, 20];
+  readonly narrow: readonly [10, 40, 50];
+  readonly collapsed: readonly [0, 50, 50];
+};
+export type PanelsLayout = keyof typeof PANELS_LAYOUTS;
+export declare const PANEL_COUNT = 3;
+export declare const PANEL_MIN = 10;
+export declare const PANEL_MAX = 80;
+/**
+ * Scenario `config` -> what both targets are mounted with. The spec is the
+ * three-pane instance (MIN 10, MAX 80, 10% steps, pane 0 collapsible at 0), so
+ * any other geometry is not modelled. `layout` only leaves the initial layout
+ * through a host write, which needs `controlled`; an uncontrolled scenario that
+ * starts elsewhere is `Unsupported` (it would have to be reached by keys, which
+ * no ported scenario needs).
+ */
+export interface PanelsConfig {
+  readonly orientation: PanelsOrientation;
+  readonly layout: PanelsLayout;
+  readonly sizes: ReadonlyArray<number>;
+  readonly controlled: boolean;
+  readonly accepts: boolean;
+}
+export declare const resizablePanelsConfig: (config: ScenarioConfig) => PanelsConfig;
+/**
+ * Resizable panels vocabulary <-> `specs/patterns/resizable-panels.qnt`. Parts:
+ * `separator:0` / `separator:1` and `pane:0..2`; keys only act on the focused
+ * separator (focus it first, as a user would). The drag is its own vocabulary
+ * (`dragStart` on a separator, `dragBy` with a ±10 delta, `dragEnd`), so the
+ * spec's snapshot + delta model and the DOM's real pointer events see the same
+ * steps. `hostLayout` is the host writing a whole layout (controlled only).
+ */
+export declare const resizablePanelsBridge: SpecBridge;
+/** The user-level steps a differential walk draws from. */
+export declare const resizablePanelsSteps: ReadonlyArray<ActionStep>;
+export declare const resizablePanelsProbe: Probe;
+//#endregion

package/dist/patterns/resizable-panels.bridge.mjs

@@ -0,0 +1,287 @@
+import { Unsupported } from "../scenario.mjs";
+//#region src/patterns/resizable-panels.bridge.ts
+const specEvent = (tag, params = {}) => ({
+	_tag: tag,
+	...params
+});
+const num = (value) => value === void 0 ? 0 : Number(value);
+/** The layouts the spec reaches by a host write (hostEqual / hostWide / ...). */
+const PANELS_LAYOUTS = {
+	initial: [
+		20,
+		40,
+		40
+	],
+	equal: [
+		30,
+		30,
+		40
+	],
+	wide: [
+		50,
+		30,
+		20
+	],
+	narrow: [
+		10,
+		40,
+		50
+	],
+	collapsed: [
+		0,
+		50,
+		50
+	]
+};
+const PANEL_COUNT = 3;
+const PANEL_MIN = 10;
+const PANEL_MAX = 80;
+const isLayout = (value) => typeof value === "string" && Object.hasOwn(PANELS_LAYOUTS, value);
+const resizablePanelsConfig = (config) => {
+	let orientation = "vertical";
+	let layout = "initial";
+	let controlled = false;
+	let accepts = true;
+	for (const [key, raw] of Object.entries(config)) if (key === "orientation" && (raw === "vertical" || raw === "horizontal")) orientation = raw;
+	else if (key === "layout" && isLayout(raw)) layout = raw;
+	else if (key === "controlled" && typeof raw === "boolean") controlled = raw;
+	else if (key === "accepts" && typeof raw === "boolean") accepts = raw;
+	else if (key === "collapsible" && raw === true) continue;
+	else if (key === "panes" && raw === 3) continue;
+	else if (key === "min" && raw === 10) continue;
+	else if (key === "max" && raw === 80) continue;
+	else throw new Unsupported(`config ${key}=${JSON.stringify(raw)}`);
+	if (!controlled && layout !== "initial") throw new Unsupported(`layout ${layout} without a controlled host`);
+	return {
+		orientation,
+		layout,
+		sizes: PANELS_LAYOUTS[layout],
+		controlled,
+		accepts
+	};
+};
+const separatorIndex = (target) => {
+	const match = /^separator:(\d+)$/.exec(target ?? "separator:0");
+	if (match === null) throw new Unsupported(`part ${target ?? ""}`);
+	const index = Number(match[1]);
+	if (index < 0 || index >= 2) throw new Unsupported(`separator ${index}`);
+	return index;
+};
+const HOST_EVENTS = {
+	initial: "hostEqual",
+	equal: "hostEqual",
+	wide: "hostWide",
+	narrow: "hostNarrow",
+	collapsed: "hostCollapsed"
+};
+const KEY_EVENTS = {
+	ArrowLeft: "left",
+	ArrowRight: "right",
+	ArrowUp: "up",
+	ArrowDown: "down",
+	Home: "home",
+	End: "end",
+	Enter: "enter"
+};
+const isKeyEvent = (key) => key in KEY_EVENTS;
+/**
+* Resizable panels vocabulary <-> `specs/patterns/resizable-panels.qnt`. Parts:
+* `separator:0` / `separator:1` and `pane:0..2`; keys only act on the focused
+* separator (focus it first, as a user would). The drag is its own vocabulary
+* (`dragStart` on a separator, `dragBy` with a ±10 delta, `dragEnd`), so the
+* spec's snapshot + delta model and the DOM's real pointer events see the same
+* steps. `hostLayout` is the host writing a whole layout (controlled only).
+*/
+const resizablePanelsBridge = {
+	setup: (config) => {
+		const c = resizablePanelsConfig(config);
+		const events = [];
+		if (c.orientation === "horizontal") events.push(specEvent("orientHorizontal"));
+		if (c.controlled) {
+			events.push(specEvent("control"));
+			if (c.accepts) events.push(specEvent("acceptRequests"));
+			if (c.layout !== "initial") events.push(specEvent(HOST_EVENTS[c.layout]));
+		}
+		return events;
+	},
+	event: (step) => {
+		switch (step.event) {
+			case "focus": return [specEvent(`focusSep${separatorIndex(step.target)}`)];
+			case "blur": return [specEvent("blur")];
+			case "key": {
+				const key = step.key ?? "";
+				if (!isKeyEvent(key)) throw new Unsupported(`key ${key}`);
+				return [specEvent(KEY_EVENTS[key])];
+			}
+			case "dragStart": return [specEvent(`dragDown${separatorIndex(step.target)}`)];
+			case "dragBy": {
+				const delta = step.value;
+				if (delta === 10) return [specEvent("dragNext")];
+				if (delta === -10) return [specEvent("dragPrev")];
+				throw new Unsupported(`drag delta ${JSON.stringify(delta)}`);
+			}
+			case "dragEnd":
+			case "dragCancel": return [specEvent("dragUp")];
+			case "hover":
+			case "unhover": return [];
+			case "prop": switch (step.prop) {
+				case "orientation":
+					if (step.value === "horizontal") return [specEvent("orientHorizontal")];
+					if (step.value === "vertical") return [specEvent("orientVertical")];
+					throw new Unsupported(`orientation ${JSON.stringify(step.value)}`);
+				case "hostLayout":
+					if (!isLayout(step.value)) throw new Unsupported(`layout ${JSON.stringify(step.value)}`);
+					if (step.value === "initial") throw new Unsupported("layout initial is not a host write");
+					return [specEvent(HOST_EVENTS[step.value])];
+				default: throw new Unsupported(`prop ${step.prop ?? ""}`);
+			}
+			default: throw new Unsupported(`event ${step.event}`);
+		}
+	},
+	value: (state) => [
+		num(state["s0"]),
+		num(state["s1"]),
+		num(state["s2"])
+	],
+	focus: (state) => {
+		switch (state["focus"]) {
+			case "sep0": return "separator:0";
+			case "sep1": return "separator:1";
+			default: return null;
+		}
+	},
+	attr: (state, target, name) => {
+		const index = separatorIndex(target);
+		switch (name) {
+			case "role": return "separator";
+			case "aria-orientation": return state["o"] === "horizontal" ? "horizontal" : "vertical";
+			case "aria-valuenow": return String(num(state[`s${index}`]));
+			case "aria-valuemin": return String(10);
+			case "aria-valuemax": return String(80);
+			case "tabindex": return "0";
+			default: throw new Unsupported(`attribute ${name} on ${target}`);
+		}
+	},
+	visible: () => [],
+	events: (before, after) => before["requests"] === after["requests"] ? [] : [["onSizesChange", [
+		num(after["rq0"]),
+		num(after["rq1"]),
+		num(after["rq2"])
+	]]]
+};
+/** The user-level steps a differential walk draws from. */
+const resizablePanelsSteps = [
+	{
+		event: "focus",
+		target: "separator:0"
+	},
+	{
+		event: "focus",
+		target: "separator:1"
+	},
+	{
+		event: "blur",
+		target: "separator:0"
+	},
+	{
+		event: "key",
+		key: "ArrowLeft",
+		target: "separator:0"
+	},
+	{
+		event: "key",
+		key: "ArrowRight",
+		target: "separator:1"
+	},
+	{
+		event: "key",
+		key: "ArrowUp",
+		target: "separator:0"
+	},
+	{
+		event: "key",
+		key: "ArrowDown",
+		target: "separator:1"
+	},
+	{
+		event: "key",
+		key: "Home",
+		target: "separator:0"
+	},
+	{
+		event: "key",
+		key: "End",
+		target: "separator:1"
+	},
+	{
+		event: "key",
+		key: "Enter",
+		target: "separator:0"
+	},
+	{
+		event: "key",
+		key: "Enter",
+		target: "separator:1"
+	},
+	{
+		event: "prop",
+		prop: "orientation",
+		value: "horizontal"
+	},
+	{
+		event: "prop",
+		prop: "orientation",
+		value: "vertical"
+	},
+	{
+		event: "prop",
+		prop: "hostLayout",
+		value: "wide"
+	},
+	{
+		event: "prop",
+		prop: "hostLayout",
+		value: "narrow"
+	},
+	{
+		event: "prop",
+		prop: "hostLayout",
+		value: "collapsed"
+	},
+	{
+		event: "prop",
+		prop: "hostLayout",
+		value: "equal"
+	},
+	{
+		event: "dragStart",
+		target: "separator:0"
+	},
+	{
+		event: "dragStart",
+		target: "separator:1"
+	},
+	{
+		event: "dragBy",
+		value: 10
+	},
+	{
+		event: "dragBy",
+		value: -10
+	},
+	{ event: "dragEnd" }
+];
+const resizablePanelsProbe = {
+	attrs: [
+		["separator:0", "role"],
+		["separator:0", "aria-orientation"],
+		["separator:0", "aria-valuenow"],
+		["separator:0", "aria-valuemin"],
+		["separator:0", "aria-valuemax"],
+		["separator:0", "tabindex"],
+		["separator:1", "aria-valuenow"]
+	],
+	events: ["onSizesChange"]
+};
+//#endregion
+export { PANELS_LAYOUTS, PANEL_COUNT, PANEL_MAX, PANEL_MIN, resizablePanelsBridge, resizablePanelsConfig, resizablePanelsProbe, resizablePanelsSteps };