@cssints/apg-specs 0.0.0-stage → 0.5.2

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

@@ -0,0 +1,54 @@
+import { ActionStep, Probe, ScenarioConfig, SpecBridge } from "../scenario.mjs";
+//#region src/apg/grid.bridge.d.ts
+/** The spec's fixed grid size (`specs/apg/grid.qnt`). */
+export declare const GRID_ROWS = 4;
+export declare const GRID_COLS = 3;
+export type GridKindName = "data" | "layout";
+export type GridFocusTargetName = "cell" | "widget";
+/**
+ * The options `createGrid` is mounted with; the bridge and the fixture share it.
+ * The spec is fixed at 4x3, so differential walks only use that size.
+ */
+export interface GridConfig {
+  readonly rows: number;
+  readonly cols: number;
+  readonly gridKind: GridKindName;
+  readonly wrapCols: boolean;
+  readonly wrapRows: boolean;
+  readonly focusTarget: GridFocusTargetName;
+  readonly gridReadonly: boolean;
+  readonly selectable: boolean;
+  readonly sortEnabled: boolean;
+  /** The host owns the selected rectangle (`value` prop present). */
+  readonly selectionControlled: boolean;
+  /** Controlled selection only: the host writes every request's intent back. */
+  readonly selectionAccepts: boolean;
+  /** Controlled selection only: a pinned packed value the host holds (rejects). */
+  readonly selectionValue: number | null;
+  /** The host owns the sort (`sortValue` prop present). */
+  readonly sortControlled: boolean;
+  /** Controlled sort only: the host writes every request's intent back. */
+  readonly sortAccepts: boolean;
+  /** Controlled sort only: a pinned packed value the host holds (rejects). */
+  readonly sortValue: number | null;
+}
+export declare const isSelectionValue: (value: number) => boolean;
+export declare const isSortValue: (value: number) => boolean;
+/**
+ * Scenario `config` -> what both targets are mounted with. Keys the primitive
+ * does not model (orientation, rtl, virtualized windows, looping callbacks,
+ * ragged columns, ...) make the scenario `Unsupported` on every target.
+ */
+export declare const normalizeGridConfig: (config: ScenarioConfig, base?: Partial<GridConfig>) => GridConfig;
+export declare const gridConfig: (config: ScenarioConfig) => GridConfig;
+/**
+ * `grid.qnt` is NAVIGATION-ONLY (map ticket rt1p): focus is roving internal
+ * state, so there is no host-owned value here and the bridge has no `value` /
+ * `events`. Controlled selection and sort are modelled by
+ * `grid-selection.bridge.ts` / `grid-sort.bridge.ts`.
+ */
+export declare const gridBridge: SpecBridge;
+/** The user-level steps a differential walk draws from. */
+export declare const gridSteps: ReadonlyArray<ActionStep>;
+export declare const gridProbe: Probe;
+//#endregion

package/dist/apg/grid.bridge.mjs

@@ -0,0 +1,441 @@
+import { Unsupported } from "../scenario.mjs";
+//#region src/apg/grid.bridge.ts
+const specEvent = (tag, params = {}) => ({
+	_tag: tag,
+	...params
+});
+const num = (value) => Number(value ?? 0);
+/** The spec's fixed grid size (`specs/apg/grid.qnt`). */
+const GRID_ROWS = 4;
+const GRID_COLS = 3;
+const DEFAULTS = {
+	rows: 4,
+	cols: 3,
+	gridKind: "data",
+	wrapCols: false,
+	wrapRows: false,
+	focusTarget: "cell",
+	gridReadonly: false,
+	selectable: false,
+	sortEnabled: false,
+	selectionControlled: false,
+	selectionAccepts: false,
+	selectionValue: null,
+	sortControlled: false,
+	sortAccepts: false,
+	sortValue: null
+};
+/** The valid packed selection values the fixed 4x3 grid can hold (0 = none). */
+const SELECTION_VALUES = /* @__PURE__ */ new Set([
+	0,
+	1,
+	5,
+	6,
+	9,
+	10,
+	11,
+	13,
+	14,
+	15,
+	16,
+	49,
+	53,
+	54,
+	57,
+	58,
+	59,
+	61,
+	62,
+	63,
+	64,
+	65,
+	69,
+	70,
+	73,
+	74,
+	75,
+	77,
+	78,
+	79,
+	80,
+	97,
+	101,
+	102,
+	105,
+	106,
+	107,
+	109,
+	110,
+	111,
+	112,
+	113,
+	117,
+	118,
+	121,
+	122,
+	123,
+	125,
+	126,
+	127,
+	128,
+	129,
+	133,
+	134,
+	137,
+	138,
+	139,
+	141,
+	142,
+	143,
+	144
+]);
+/** The valid packed sort values: -1 unsorted, else 2*column + (desc ? 1 : 0). */
+const SORT_VALUES = /* @__PURE__ */ new Set([
+	-1,
+	0,
+	1,
+	4,
+	5
+]);
+const isSelectionValue = (value) => SELECTION_VALUES.has(value);
+const isSortValue = (value) => SORT_VALUES.has(value);
+const positiveInt = (key, value) => {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throw new Unsupported(`config ${key}=${JSON.stringify(value)}`);
+	return value;
+};
+const bool = (key, value) => {
+	if (typeof value !== "boolean") throw new Unsupported(`config ${key}=${JSON.stringify(value)}`);
+	return value;
+};
+/**
+* Scenario `config` -> what both targets are mounted with. Keys the primitive
+* does not model (orientation, rtl, virtualized windows, looping callbacks,
+* ragged columns, ...) make the scenario `Unsupported` on every target.
+*/
+const normalizeGridConfig = (config, base = {}) => {
+	let rows = base.rows ?? DEFAULTS.rows;
+	let cols = base.cols ?? DEFAULTS.cols;
+	let gridKind = base.gridKind ?? DEFAULTS.gridKind;
+	let wrapCols = base.wrapCols ?? DEFAULTS.wrapCols;
+	let wrapRows = base.wrapRows ?? DEFAULTS.wrapRows;
+	let focusTarget = base.focusTarget ?? DEFAULTS.focusTarget;
+	let gridReadonly = base.gridReadonly ?? DEFAULTS.gridReadonly;
+	let selectable = base.selectable ?? DEFAULTS.selectable;
+	let sortEnabled = base.sortEnabled ?? DEFAULTS.sortEnabled;
+	let selectionControlled = base.selectionControlled ?? DEFAULTS.selectionControlled;
+	let selectionValue = base.selectionValue ?? DEFAULTS.selectionValue;
+	let sortControlled = base.sortControlled ?? DEFAULTS.sortControlled;
+	let sortValue = base.sortValue ?? DEFAULTS.sortValue;
+	for (const [key, value] of Object.entries(config)) switch (key) {
+		case "rows":
+			rows = positiveInt(key, value);
+			break;
+		case "cols":
+			cols = positiveInt(key, value);
+			break;
+		case "layout":
+			if (value !== "grid") throw new Unsupported(`config layout=${JSON.stringify(value)}`);
+			break;
+		case "gridKind":
+			if (value !== "data" && value !== "layout") throw new Unsupported(`config gridKind=${JSON.stringify(value)}`);
+			gridKind = value;
+			break;
+		case "wrapCols":
+			wrapCols = bool(key, value);
+			break;
+		case "wrapRows":
+			wrapRows = bool(key, value);
+			break;
+		case "focusTarget":
+			if (value !== "cell" && value !== "widget") throw new Unsupported(`config focusTarget=${JSON.stringify(value)}`);
+			focusTarget = value;
+			break;
+		case "gridReadonly":
+		case "readonly":
+			gridReadonly = bool(key, value);
+			break;
+		case "selectable":
+			selectable = bool(key, value);
+			break;
+		case "sortEnabled":
+			sortEnabled = bool(key, value);
+			break;
+		case "controlled":
+			if (typeof value !== "boolean") throw new Unsupported(`config controlled=${JSON.stringify(value)}`);
+			selectionControlled ||= value;
+			break;
+		case "selection":
+			if (typeof value !== "number" || !SELECTION_VALUES.has(value)) throw new Unsupported(`config selection=${JSON.stringify(value)}`);
+			selectionValue = value;
+			selectionControlled = true;
+			break;
+		case "sortControlled":
+			if (typeof value !== "boolean") throw new Unsupported(`config sortControlled=${JSON.stringify(value)}`);
+			sortControlled ||= value;
+			break;
+		case "sort":
+			if (typeof value !== "number" || !SORT_VALUES.has(value)) throw new Unsupported(`config sort=${JSON.stringify(value)}`);
+			sortValue = value;
+			sortControlled = true;
+			break;
+		case "enableHomeAndEndKeys":
+			if (value !== true) throw new Unsupported(`config ${key}=${JSON.stringify(value)}`);
+			break;
+		case "loopFocus":
+			if (value !== false) throw new Unsupported(`config loopFocus=${JSON.stringify(value)}`);
+			break;
+		default: throw new Unsupported(`config ${key}=${JSON.stringify(value)}`);
+	}
+	if (gridKind === "data") {
+		wrapCols = false;
+		wrapRows = false;
+	}
+	return {
+		rows,
+		cols,
+		gridKind,
+		wrapCols,
+		wrapRows,
+		focusTarget,
+		gridReadonly,
+		selectable,
+		sortEnabled,
+		selectionControlled,
+		selectionAccepts: selectionControlled && selectionValue === null,
+		selectionValue,
+		sortControlled,
+		sortAccepts: sortControlled && sortValue === null,
+		sortValue
+	};
+};
+const gridConfig = (config) => normalizeGridConfig(config);
+const CELL = /^cell:(\d+),(\d+)$/;
+const WIDGET = /^cell:(\d+),(\d+)\/widget$/;
+const cellOf = (target) => {
+	const match = CELL.exec(target ?? "");
+	if (match === null) throw new Unsupported(`target ${target ?? ""}`);
+	return {
+		row: Number(match[1]),
+		col: Number(match[2])
+	};
+};
+const widgetOf = (target) => {
+	const match = WIDGET.exec(target ?? "");
+	if (match === null) throw new Unsupported(`target ${target ?? ""}`);
+	return {
+		row: Number(match[1]),
+		col: Number(match[2])
+	};
+};
+const isGridTarget = (target) => target === void 0 || target === "grid";
+/** The spec key pool (`grid.qnt`'s `key` nondet set). */
+const GRID_KEYS = /* @__PURE__ */ new Set([
+	"ArrowRight",
+	"ArrowLeft",
+	"ArrowDown",
+	"ArrowUp",
+	"Home",
+	"End",
+	"Control+Home",
+	"Control+End",
+	"PageUp",
+	"PageDown",
+	"Enter",
+	"F2",
+	"Escape",
+	"a",
+	"Tab",
+	"Shift+Tab"
+]);
+/**
+* `grid.qnt` is NAVIGATION-ONLY (map ticket rt1p): focus is roving internal
+* state, so there is no host-owned value here and the bridge has no `value` /
+* `events`. Controlled selection and sort are modelled by
+* `grid-selection.bridge.ts` / `grid-sort.bridge.ts`.
+*/
+const gridBridge = {
+	setup: (config) => {
+		const value = gridConfig(config);
+		return [
+			...value.gridKind === "layout" ? [specEvent("set_kind", { choice: "layout" })] : [],
+			...value.wrapCols ? [specEvent("set_wrap_cols", { flag: true })] : [],
+			...value.wrapRows ? [specEvent("set_wrap_rows", { flag: true })] : [],
+			...value.focusTarget === "widget" ? [specEvent("set_focus_target", { choice: "widget" })] : [],
+			...value.gridReadonly ? [specEvent("set_readonly", { flag: true })] : []
+		];
+	},
+	event: (step) => {
+		switch (step.event) {
+			case "focus": {
+				if (isGridTarget(step.target)) return [specEvent("focus_in")];
+				const { row, col } = cellOf(step.target);
+				return [specEvent("click", { cell: BigInt(row * 3 + col) })];
+			}
+			case "blur": return [specEvent("focus_out")];
+			case "click": {
+				const { row, col } = cellOf(step.target);
+				return [specEvent("click", { cell: BigInt(row * 3 + col) })];
+			}
+			case "key":
+				if (!GRID_KEYS.has(step.key ?? "")) throw new Unsupported(`key ${step.key ?? ""}`);
+				return [specEvent("key", { key: step.key ?? "" })];
+			case "hover":
+			case "unhover": return [];
+			case "prop": switch (step.prop) {
+				case "gridKind":
+				case "kind":
+					if (step.value !== "data" && step.value !== "layout") throw new Unsupported(`prop ${step.prop}=${JSON.stringify(step.value)}`);
+					return [specEvent("set_kind", { choice: step.value })];
+				case "wrapCols": return [specEvent("set_wrap_cols", { flag: step.value === true })];
+				case "wrapRows": return [specEvent("set_wrap_rows", { flag: step.value === true })];
+				case "focusTarget":
+					if (step.value !== "cell" && step.value !== "widget") throw new Unsupported(`prop focusTarget=${JSON.stringify(step.value)}`);
+					return [specEvent("set_focus_target", { choice: step.value })];
+				case "readonly":
+				case "gridReadonly": return [specEvent("set_readonly", { flag: step.value === true })];
+				default: throw new Unsupported(`prop ${step.prop ?? ""}`);
+			}
+			default: throw new Unsupported(`event ${step.event}`);
+		}
+	},
+	focus: (state) => {
+		if (state["hasFocus"] !== true) return null;
+		return `cell:${num(state["row"])},${num(state["col"])}`;
+	},
+	attr: (state, target, name) => {
+		if (isGridTarget(target)) {
+			if (name === "aria-rowcount") return String(4);
+			if (name === "aria-colcount") return String(3);
+			if (name === "aria-readonly") return state["gridReadonly"] === true ? "true" : "false";
+			throw new Unsupported(`attribute ${name} on grid`);
+		}
+		if (WIDGET.exec(target) !== null) {
+			if (name !== "tabindex") throw new Unsupported(`attribute ${name} on ${target}`);
+			const cell = widgetOf(target);
+			return state["focusTarget"] === "widget" && cell.row === num(state["row"]) && cell.col === num(state["col"]) ? "0" : "-1";
+		}
+		const cell = cellOf(target);
+		switch (name) {
+			case "tabindex": return state["focusTarget"] === "cell" && cell.row === num(state["row"]) && cell.col === num(state["col"]) ? "0" : "-1";
+			case "aria-rowindex": return String(cell.row + 1);
+			case "aria-colindex": return String(cell.col + 1);
+			case "aria-readonly": return state["gridReadonly"] === true || cell.col === 2 ? "true" : "false";
+			case "aria-selected": throw new Unsupported("selection is modelled by grid-selection.bridge");
+			default: throw new Unsupported(`attribute ${name} on ${target}`);
+		}
+	},
+	visible: () => [],
+	events: () => []
+};
+/** The user-level steps a differential walk draws from. */
+const gridSteps = [
+	...Array.from({ length: 12 }, (_, index) => ({
+		event: "click",
+		target: `cell:${Math.floor(index / 3)},${index % 3}`
+	})),
+	...[
+		"ArrowRight",
+		"ArrowLeft",
+		"ArrowDown",
+		"ArrowUp",
+		"Home",
+		"End",
+		"Control+Home",
+		"Control+End",
+		"PageUp",
+		"PageDown",
+		"Enter",
+		"F2",
+		"Escape",
+		"a",
+		"Tab",
+		"Shift+Tab"
+	].map((key) => ({
+		event: "key",
+		key,
+		target: "grid"
+	})),
+	{
+		event: "focus",
+		target: "grid"
+	},
+	{
+		event: "blur",
+		target: "grid"
+	},
+	{
+		event: "prop",
+		prop: "gridKind",
+		value: "layout"
+	},
+	{
+		event: "prop",
+		prop: "gridKind",
+		value: "data"
+	},
+	{
+		event: "prop",
+		prop: "wrapCols",
+		value: true
+	},
+	{
+		event: "prop",
+		prop: "wrapCols",
+		value: false
+	},
+	{
+		event: "prop",
+		prop: "wrapRows",
+		value: true
+	},
+	{
+		event: "prop",
+		prop: "wrapRows",
+		value: false
+	},
+	{
+		event: "prop",
+		prop: "focusTarget",
+		value: "widget"
+	},
+	{
+		event: "prop",
+		prop: "focusTarget",
+		value: "cell"
+	},
+	{
+		event: "prop",
+		prop: "readonly",
+		value: true
+	},
+	{
+		event: "prop",
+		prop: "readonly",
+		value: false
+	}
+];
+const GRID_CELL_ATTRS = [
+	"tabindex",
+	"aria-rowindex",
+	"aria-colindex",
+	"aria-readonly"
+];
+const cellTargets = () => Array.from({ length: 12 }, (_, index) => {
+	const row = Math.floor(index / 3);
+	const col = index % 3;
+	return GRID_CELL_ATTRS.map((name) => [`cell:${row},${col}`, name]);
+}).flat();
+const gridProbe = {
+	attrs: [
+		["grid", "aria-rowcount"],
+		["grid", "aria-colcount"],
+		["grid", "aria-readonly"],
+		...cellTargets(),
+		...Array.from({ length: 12 }, (_, index) => {
+			return [`cell:${Math.floor(index / 3)},${index % 3}/widget`, "tabindex"];
+		})
+	],
+	events: []
+};
+//#endregion
+export { GRID_COLS, GRID_ROWS, gridBridge, gridConfig, gridProbe, gridSteps, isSelectionValue, isSortValue, normalizeGridConfig };