praxis-kit 0.1.1 → 1.0.2

package/dist/preact/index.js

@@ -18,11 +18,6 @@ function applyDisplayName(component, name) {
 	Object.assign(component, { displayName: name ?? "PolymorphicComponent" });
 }
 //#endregion
-//#region ../../lib/adapter-utils/src/runtime/define-component.ts
-function defineContractComponent(options) {
-	return (factory) => factory(options);
-}
-//#endregion
 //#region ../../lib/adapter-utils/src/runtime/assemble-compound-component.ts
 /**
 * Assembles a compound component by attaching sub-components to a
@@ -1590,72 +1585,100 @@ var InvariantBase = class {
 	}
 };
 //#endregion
-//#region ../../lib/contract/src/aria/spec/roles/required-properties.ts
-const REQUIRED_ARIA_PROPERTIES = {
-	combobox: ["aria-expanded"],
-	option: ["aria-selected"],
-	slider: ["aria-valuenow"],
-	scrollbar: ["aria-controls", "aria-valuenow"],
-	spinbutton: ["aria-valuenow"]
-};
-//#endregion
-//#region ../../lib/contract/src/aria/spec/roles/name-required.ts
-const NAME_REQUIRED_ROLES = /* @__PURE__ */ new Set(["img"]);
-//#endregion
-//#region ../../lib/contract/src/aria/spec/roles/name-prohibited.ts
-const NAME_PROHIBITED_ROLES = /* @__PURE__ */ new Set([
-	"caption",
-	"code",
-	"deletion",
-	"emphasis",
-	"generic",
-	"insertion",
-	"none",
-	"paragraph",
-	"presentation",
-	"strong",
-	"subscript",
-	"superscript"
-]);
-const NAME_PROHIBITED_ATTRIBUTES = ["aria-label", "aria-labelledby"];
-//#endregion
-//#region ../../lib/contract/src/aria/spec/validators/required-properties-validator.ts
-const NO_VIOLATIONS$1 = [{ valid: true }];
-function requiredAttributeByRole(roles, attribute) {
-	return Object.fromEntries([...roles].map((role) => [role, [attribute]]));
-}
+//#region ../../lib/contract/src/aria/plan-cache.ts
 /**
-* Reports missing attributes required by an element's effective ARIA role.
+* Validation-plan cache machinery for `AriaPolicyEngine`: computing a cache key from a
+* (tag, props) usage site, and diffing/replaying the props transformation a validation pass
+* produced (an {@link AriaPlan}'s `removals`/`updates`) without re-running the ARIA rule
+* pipeline itself. Extracted because these four functions are a cohesive subsystem in their own
+* right — a small revalidation-caching scheme — not specifically ARIA *policy*; the actual
+* cache storage (an `LRUCache` instance) stays owned by `AriaPolicyEngine` itself, since it's
+* per-engine-instance state, not something this module needs to hold.
+*/
+/**
+* Cache key covering only the aria-relevant subset of props (tag + role + aria-* attrs) —
+* exactly what the built-in pipeline reads. Non-aria props (className, onClick, etc.) do
+* not affect built-in ARIA decisions and are excluded so cache hits survive re-renders
+* that only change non-aria props. This key alone is unsound for a policy engine's own
+* extra rules, which may read arbitrary props outside this set — extend it with
+* {@link extraRulesKeySuffix}, or bypass the cache, to account for that.
 *
-* Shared by validators that differ only in their role-to-attribute mapping and diagnostic
-* generation.
+* Returns `null` (meaning "don't cache") when `tag` isn't a plain intrinsic string tag —
+* `isString(tag)` inline rather than importing `AriaPolicyEngine`'s own `isIntrinsicTag`: the
+* check is a one-liner, and importing it back from the engine module would be a needless
+* dependency in the other direction for a plan-cache module the engine itself depends on.
 */
-function checkRequiredAttributes(requirement, { props, effectiveRole }) {
-	if (!effectiveRole) return NO_VIOLATIONS$1;
-	const requiredAttributes = requirement.attributesByRole[effectiveRole];
-	if (!requiredAttributes) return NO_VIOLATIONS$1;
-	const results = [];
-	for (const attribute of requiredAttributes) {
-		if (attribute in props) continue;
-		results.push({
-			valid: false,
-			fixable: false,
-			severity: "warning",
-			attribute,
-			diagnostic: requirement.diagnosticFor(attribute, effectiveRole)
-		});
+function createPlanKey(tag, props) {
+	if (!isString(tag)) return null;
+	const parts = [tag];
+	if (isString(props.role)) parts.push(`role:${props.role}`);
+	if (tag === "input" && isString(props.type)) parts.push(`type:${props.type}`);
+	if (tag === "img") parts.push(`alt:${props.alt === "" ? "empty" : "present"}`);
+	const ariaEntries = [];
+	iterate.forEachEntry(props, (k, v) => {
+		if (!k.startsWith("aria-")) return;
+		if (!isString(v) && !isNumber(v) && typeof v !== "boolean") return;
+		ariaEntries.push(`${k}:${String(v)}`);
+	});
+	if (ariaEntries.length > 0) parts.push(...ariaEntries.sort());
+	return parts.join("|");
+}
+/**
+* Extends the base cache key with the props each extra rule declares it reads (`readsProps`).
+* Returns `null` — meaning "don't cache" — if any extra rule omits `readsProps` (it may read
+* arbitrary props the key can't account for) or if a declared prop's value isn't a primitive
+* (object/array identity isn't stably representable in a string key).
+*/
+function extraRulesKeySuffix(extraRules, props) {
+	const parts = [];
+	for (const rule of extraRules) {
+		const readsProps = rule.readsProps;
+		if (!isNonNull(readsProps)) return null;
+		for (const propKey of readsProps) {
+			const v = props[propKey];
+			if (isDefined(v) && !isString(v) && !isNumber(v) && typeof v !== "boolean") return null;
+			parts.push(`x:${propKey}:${String(v)}`);
+		}
 	}
-	return results;
+	return parts.sort().join("|");
+}
+/** Diffs a validation pass's input/output props into a replayable plan: which keys were removed
+*  entirely, and which keys were added or changed value (and to what). */
+function computePlan(inputProps, resultProps) {
+	const removals = /* @__PURE__ */ new Set();
+	const updates = {};
+	iterate.forEachKey(inputProps, (key) => {
+		if (!(key in resultProps)) removals.add(key);
+	});
+	iterate.forEachEntry(resultProps, (key, resultVal) => {
+		if (inputProps[key] !== resultVal) updates[key] = resultVal;
+	});
+	return {
+		removals,
+		updates
+	};
+}
+/** Replays a cached plan's removals/updates against a fresh `props` object, without re-running
+*  the rule pipeline that originally produced the plan. */
+function applyPlan(props, removals, updates) {
+	const hasRemovals = removals.size > 0;
+	const hasUpdates = Object.keys(updates).length > 0;
+	if (!hasRemovals && !hasUpdates) return props;
+	const next = {};
+	iterate.forEachEntry(props, (k, v) => {
+		if (!removals.has(k)) next[k] = v;
+	});
+	Object.assign(next, updates);
+	return next;
 }
 //#endregion
-//#region ../../lib/contract/src/aria/spec/roles/live-region.ts
-const LIVE_REGION_ROLES = /* @__PURE__ */ new Map([
-	["alert", "assertive"],
-	["status", "polite"],
-	["log", "polite"],
-	["timer", "off"]
+//#region ../../lib/contract/src/aria/spec/attributes/aria-relevant-tokens.ts
+const VALID_RELEVANT_TOKENS = /* @__PURE__ */ new Set([
+	"additions",
+	"removals",
+	"text",
+	"all"
 ]);
-const ATOMIC_REQUIREMENTS = requiredAttributeByRole(LIVE_REGION_ROLES.keys(), "aria-atomic");
 //#endregion
 //#region ../../lib/contract/src/aria/spec/attributes/aria-value-types.ts
 const ARIA_VALUE_TYPES = /* @__PURE__ */ new Map([
@@ -1780,24 +1803,6 @@ const ARIA_VALUE_TYPES = /* @__PURE__ */ new Map([
 	}]
 ]);
 //#endregion
-//#region ../../lib/contract/src/aria/spec/attributes/aria-relevant-tokens.ts
-const VALID_RELEVANT_TOKENS = /* @__PURE__ */ new Set([
-	"additions",
-	"removals",
-	"text",
-	"all"
-]);
-//#endregion
-//#region ../../lib/contract/src/aria/spec/elements/heading-implicit-levels.ts
-const HEADING_IMPLICIT_LEVELS = /* @__PURE__ */ new Map([
-	["h1", 1],
-	["h2", 2],
-	["h3", 3],
-	["h4", 4],
-	["h5", 5],
-	["h6", 6]
-]);
-//#endregion
 //#region ../../lib/contract/src/aria/spec/elements/focusable.ts
 function parseTabIndex(raw) {
 	if (typeof raw === "number") return Number.isInteger(raw) ? raw : void 0;
@@ -1848,24 +1853,156 @@ function isPotentiallyFocusable(tag, props) {
 	}
 }
 //#endregion
-//#region ../../lib/contract/src/aria/aria-policy-engine.ts
+//#region ../../lib/contract/src/aria/spec/elements/heading-implicit-levels.ts
+const HEADING_IMPLICIT_LEVELS = /* @__PURE__ */ new Map([
+	["h1", 1],
+	["h2", 2],
+	["h3", 3],
+	["h4", 4],
+	["h5", 5],
+	["h6", 6]
+]);
+//#endregion
+//#region ../../lib/contract/src/aria/spec/validators/required-properties-validator.ts
 const NO_VIOLATIONS = [{ valid: true }];
-const NO_VARIANT_KEYS = /* @__PURE__ */ new Set();
-function isIntrinsicTag(tag) {
-	return isString(tag);
+function requiredAttributeByRole(roles, attribute) {
+	return Object.fromEntries([...roles].map((role) => [role, [attribute]]));
 }
-function omitProp(obj, key) {
-	const { [key]: _, ...rest } = obj;
-	return rest;
+/**
+* Reports missing attributes required by an element's effective ARIA role.
+*
+* Shared by validators that differ only in their role-to-attribute mapping and diagnostic
+* generation.
+*/
+function checkRequiredAttributes(requirement, { props, effectiveRole }) {
+	if (!effectiveRole) return NO_VIOLATIONS;
+	const requiredAttributes = requirement.attributesByRole[effectiveRole];
+	if (!requiredAttributes) return NO_VIOLATIONS;
+	const results = [];
+	for (const attribute of requiredAttributes) {
+		if (attribute in props) continue;
+		results.push({
+			valid: false,
+			fixable: false,
+			severity: "warning",
+			attribute,
+			diagnostic: requirement.diagnosticFor(attribute, effectiveRole)
+		});
+	}
+	return results;
 }
+//#endregion
+//#region ../../lib/contract/src/aria/spec/roles/live-region.ts
+const LIVE_REGION_ROLES = /* @__PURE__ */ new Map([
+	["alert", "assertive"],
+	["status", "polite"],
+	["log", "polite"],
+	["timer", "off"]
+]);
+const ATOMIC_REQUIREMENTS = requiredAttributeByRole(LIVE_REGION_ROLES.keys(), "aria-atomic");
+//#endregion
+//#region ../../lib/contract/src/aria/spec/roles/name-prohibited.ts
+const NAME_PROHIBITED_ROLES = /* @__PURE__ */ new Set([
+	"caption",
+	"code",
+	"deletion",
+	"emphasis",
+	"generic",
+	"insertion",
+	"none",
+	"paragraph",
+	"presentation",
+	"strong",
+	"subscript",
+	"superscript"
+]);
+const NAME_PROHIBITED_ATTRIBUTES = ["aria-label", "aria-labelledby"];
+//#endregion
+//#region ../../lib/contract/src/aria/spec/roles/name-required.ts
+const NAME_REQUIRED_ROLES = /* @__PURE__ */ new Set(["img"]);
+//#endregion
+//#region ../../lib/contract/src/aria/spec/roles/required-properties.ts
+const REQUIRED_ARIA_PROPERTIES = {
+	combobox: ["aria-expanded"],
+	option: ["aria-selected"],
+	slider: ["aria-valuenow"],
+	scrollbar: ["aria-controls", "aria-valuenow"],
+	spinbutton: ["aria-valuenow"]
+};
+//#endregion
+//#region ../../lib/contract/src/aria/value-validation.ts
+/**
+* ARIA attribute value type system: what counts as a valid value for a given
+* {@link AriaValueType}, and how to describe what was expected when it isn't. Extracted from
+* `AriaPolicyEngine` — these three functions are cohesive on their own (they're describing a
+* type system, not policy), and `#checkAriaAttributeValues` (kept in `aria-policy-engine.ts`
+* alongside every other rule implementation — see that file's own pipeline) is now just a thin
+* caller of {@link isValidAriaValue}/{@link describeExpected}.
+*/
+/**
+* Strict numeric coercion for ARIA attribute values. Unlike `parseFloat`/`parseInt`, the whole
+* string must be a number — `"12abc"` is rejected, not read as `12` — and an empty / whitespace
+* string is rejected rather than coerced to `0` the way `Number("")` would.
+*
+* Exported (not local to `isValidAriaValue`) because `AriaPolicyEngine.#checkRedundantAriaLevel`
+* also needs it, independent of the general ARIA value-type check this module otherwise exists
+* for — `aria-level`'s "redundant" check is about comparing a numeric attribute value to a
+* known implicit level, not about validating the value's type.
+*/
 function strictNumeric(value) {
-	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
-	if (typeof value !== "string") return void 0;
+	if (isNumber(value)) return Number.isFinite(value) ? value : void 0;
+	if (!isString(value)) return void 0;
 	const trimmed = value.trim();
 	if (trimmed === "") return void 0;
 	const n = Number(trimmed);
 	return Number.isFinite(n) ? n : void 0;
 }
+/** Returns whether `value` satisfies `type`'s own value-type constraint (boolean/tristate/
+*  number/integer/enum) — the WAI-ARIA attribute value type system, independent of which
+*  attribute or role it's being checked for. */
+function isValidAriaValue(value, type) {
+	switch (type.kind) {
+		case "boolean": return value === "true" || value === "false" || value === true || value === false;
+		case "tristate": return value === "true" || value === "false" || value === "mixed" || value === true || value === false;
+		case "number": return strictNumeric(value) !== void 0;
+		case "integer": {
+			const n = strictNumeric(value);
+			if (isUndefined(n) || !Number.isInteger(n)) return false;
+			if (isDefined(type.min) && n < type.min) return false;
+			if (isDefined(type.max) && n > type.max) return false;
+			return true;
+		}
+		case "enum": return isString(value) && type.values.has(value);
+	}
+}
+/** Describes what a valid value for `type` looks like, for use in an invalid-value diagnostic
+*  message (e.g. `aria-valuenow` got `"abc"`, expected "a finite number"). */
+function describeExpected(type) {
+	switch (type.kind) {
+		case "boolean": return "\"true\" or \"false\"";
+		case "tristate": return "\"true\", \"false\", or \"mixed\"";
+		case "number": return "a finite number";
+		case "integer": {
+			const parts = ["an integer"];
+			if (isDefined(type.min) && isDefined(type.max)) parts.push(`between ${type.min} and ${type.max}`);
+			else if (isDefined(type.min)) parts.push(`≥ ${type.min}`);
+			else if (isDefined(type.max)) parts.push(`≤ ${type.max}`);
+			return parts.join(" ");
+		}
+		case "enum": return [...type.values].map((v) => `"${v}"`).join(", ");
+	}
+}
+//#endregion
+//#region ../../lib/contract/src/aria/aria-policy-engine.ts
+const VALID_RESULT = [{ valid: true }];
+const NO_VARIANT_KEYS = /* @__PURE__ */ new Set();
+function isIntrinsicTag(tag) {
+	return isString(tag);
+}
+function omitProp(obj, key) {
+	const { [key]: _, ...rest } = obj;
+	return rest;
+}
 var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 	#extraRules;
 	#variantKeys;
@@ -1998,73 +2135,20 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 			else this.warn(d);
 		});
 	}
-	static #createPlanKey(tag, props) {
-		if (!isIntrinsicTag(tag)) return null;
-		const parts = [tag];
-		if (typeof props.role === "string") parts.push(`role:${props.role}`);
-		if (tag === "input" && typeof props.type === "string") parts.push(`type:${props.type}`);
-		if (tag === "img") parts.push(`alt:${props.alt === "" ? "empty" : "present"}`);
-		const ariaEntries = [];
-		iterate.forEachEntry(props, (k, v) => {
-			if (!k.startsWith("aria-")) return;
-			if (!isString(v) && !isNumber(v) && typeof v !== "boolean") return;
-			ariaEntries.push(`${k}:${String(v)}`);
-		});
-		if (ariaEntries.length > 0) parts.push(...ariaEntries.sort());
-		return parts.join("|");
-	}
-	static #extraRulesKeySuffix(extraRules, props) {
-		const parts = [];
-		for (const rule of extraRules) {
-			const readsProps = rule.readsProps;
-			if (!isNonNull(readsProps)) return null;
-			for (const propKey of readsProps) {
-				const v = props[propKey];
-				if (v !== void 0 && !isString(v) && !isNumber(v) && typeof v !== "boolean") return null;
-				parts.push(`x:${propKey}:${String(v)}`);
-			}
-		}
-		return parts.sort().join("|");
-	}
-	static #computePlan(inputProps, resultProps) {
-		const removals = /* @__PURE__ */ new Set();
-		const updates = {};
-		iterate.forEachKey(inputProps, (key) => {
-			if (!(key in resultProps)) removals.add(key);
-		});
-		iterate.forEachEntry(resultProps, (key, resultVal) => {
-			if (inputProps[key] !== resultVal) updates[key] = resultVal;
-		});
-		return {
-			removals,
-			updates
-		};
-	}
-	static #applyPlan(props, removals, updates) {
-		const hasRemovals = removals.size > 0;
-		const hasUpdates = Object.keys(updates).length > 0;
-		if (!hasRemovals && !hasUpdates) return props;
-		const next = {};
-		iterate.forEachEntry(props, (k, v) => {
-			if (!removals.has(k)) next[k] = v;
-		});
-		Object.assign(next, updates);
-		return next;
-	}
 	validate(tag, props, extraProps) {
 		const ruleProps = extraProps ?? props;
-		const baseKey = AriaPolicyEngine.#createPlanKey(tag, props);
+		const baseKey = createPlanKey(tag, props);
 		let key = baseKey;
 		if (this.#extraRules.length > 0) {
-			const suffix = AriaPolicyEngine.#extraRulesKeySuffix(this.#extraRules, ruleProps);
+			const suffix = extraRulesKeySuffix(this.#extraRules, ruleProps);
 			key = isNonNull(baseKey) && isNonNull(suffix) ? `${baseKey}|${suffix}` : null;
 		}
 		if (!isNull(key)) {
 			const cached = this.#planCache.get(key);
-			if (cached !== void 0) {
+			if (isDefined(cached)) {
 				if (cached.violations.length > 0) this.report(cached.violations);
 				return {
-					props: AriaPolicyEngine.#applyPlan(props, cached.removals, cached.updates),
+					props: applyPlan(props, cached.removals, cached.updates),
 					violations: cached.violations
 				};
 			}
@@ -2072,7 +2156,7 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		const result = this.#extraRules.length ? AriaPolicyEngine.#evaluateWithRules(tag, props, this.#extraRules, extraProps, this.#variantKeys) : AriaPolicyEngine.evaluate(tag, props);
 		if (result.violations.length > 0) this.report(result.violations);
 		if (!isNull(key)) {
-			const { removals, updates } = AriaPolicyEngine.#computePlan(props, result.props);
+			const { removals, updates } = computePlan(props, result.props);
 			const plan = {
 				removals,
 				updates,
@@ -2163,7 +2247,7 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 	];
 	static #checkInvalidRoleOverride({ tag, props, implicitRole }) {
 		const role = props.role;
-		if (!implicitRole || !role || role === implicitRole) return NO_VIOLATIONS;
+		if (!implicitRole || isUndefined(role) || role === implicitRole) return VALID_RESULT;
 		if (isStrongImplicitRole(tag) && role === "region") {
 			const diagnostic = HtmlDiagnostics.implicitRoleOverride(tag, implicitRole, role);
 			return [{
@@ -2174,11 +2258,11 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 				diagnostic
 			}];
 		}
-		return NO_VIOLATIONS;
+		return VALID_RESULT;
 	}
 	static #checkRedundantRole({ tag, props, implicitRole }) {
 		const role = props.role;
-		if (!implicitRole || !role || role !== implicitRole) return NO_VIOLATIONS;
+		if (!implicitRole || isUndefined(role) || role !== implicitRole) return VALID_RESULT;
 		const diagnostic = HtmlDiagnostics.implicitRoleRedundant(tag, implicitRole);
 		return [{
 			valid: false,
@@ -2189,8 +2273,8 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		}];
 	}
 	static #checkStandaloneRegion({ tag, props, implicitRole }) {
-		if (props.role !== "region") return NO_VIOLATIONS;
-		if (!hasStandaloneRole(tag)) return NO_VIOLATIONS;
+		if (props.role !== "region") return VALID_RESULT;
+		if (!hasStandaloneRole(tag)) return VALID_RESULT;
 		const diagnostic = HtmlDiagnostics.standaloneRegionOverride(tag, implicitRole ?? tag);
 		return [{
 			valid: false,
@@ -2201,7 +2285,7 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		}];
 	}
 	static #checkInvalidAriaAttributes({ tag, props, effectiveRole }) {
-		if (effectiveRole === "none" || effectiveRole === "presentation") return NO_VIOLATIONS;
+		if (effectiveRole === "none" || effectiveRole === "presentation") return VALID_RESULT;
 		const results = [];
 		iterate.forEachEntry(props, (key) => {
 			if (!key.startsWith("aria-")) return;
@@ -2218,63 +2302,33 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		});
 		return results;
 	}
-	static #isValidAriaValue(value, type) {
-		switch (type.kind) {
-			case "boolean": return value === "true" || value === "false" || value === true || value === false;
-			case "tristate": return value === "true" || value === "false" || value === "mixed" || value === true || value === false;
-			case "number": return strictNumeric(value) !== void 0;
-			case "integer": {
-				const n = strictNumeric(value);
-				if (n === void 0 || !Number.isInteger(n)) return false;
-				if (type.min !== void 0 && n < type.min) return false;
-				if (type.max !== void 0 && n > type.max) return false;
-				return true;
-			}
-			case "enum": return typeof value === "string" && type.values.has(value);
-		}
-	}
-	static #describeExpected(type) {
-		switch (type.kind) {
-			case "boolean": return "\"true\" or \"false\"";
-			case "tristate": return "\"true\", \"false\", or \"mixed\"";
-			case "number": return "a finite number";
-			case "integer": {
-				const parts = ["an integer"];
-				if (type.min !== void 0 && type.max !== void 0) parts.push(`between ${type.min} and ${type.max}`);
-				else if (type.min !== void 0) parts.push(`≥ ${type.min}`);
-				else if (type.max !== void 0) parts.push(`≤ ${type.max}`);
-				return parts.join(" ");
-			}
-			case "enum": return [...type.values].map((v) => `"${v}"`).join(", ");
-		}
-	}
 	static #checkAriaAttributeValues({ props, effectiveRole }) {
-		if (effectiveRole === "none" || effectiveRole === "presentation") return NO_VIOLATIONS;
+		if (effectiveRole === "none" || effectiveRole === "presentation") return VALID_RESULT;
 		const results = [];
 		iterate.forEachEntry(props, (key, value) => {
 			if (!key.startsWith("aria-")) return;
 			const type = ARIA_VALUE_TYPES.get(key);
 			if (!isNonNull(type)) return;
-			if (AriaPolicyEngine.#isValidAriaValue(value, type)) return;
+			if (isValidAriaValue(value, type)) return;
 			results.push({
 				valid: false,
 				fixable: true,
 				severity: "warning",
 				attribute: key,
-				diagnostic: AriaDiagnostics.invalidAttributeValue(key, value, AriaPolicyEngine.#describeExpected(type)),
+				diagnostic: AriaDiagnostics.invalidAttributeValue(key, value, describeExpected(type)),
 				fix: AriaPolicyEngine.#makeRemoveAttributeFix(key)
 			});
 		});
 		return results;
 	}
 	static #checkRedundantAriaLevel({ tag, props, effectiveRole }) {
-		if (effectiveRole === "none" || effectiveRole === "presentation") return NO_VIOLATIONS;
+		if (effectiveRole === "none" || effectiveRole === "presentation") return VALID_RESULT;
 		const implicitLevel = HEADING_IMPLICIT_LEVELS.get(tag);
-		if (!isNonNull(implicitLevel)) return NO_VIOLATIONS;
+		if (!isNonNull(implicitLevel)) return VALID_RESULT;
 		const raw = props["aria-level"];
-		if (!isNonNull(raw)) return NO_VIOLATIONS;
+		if (!isNonNull(raw)) return VALID_RESULT;
 		const n = strictNumeric(raw);
-		if (n === void 0 || n !== implicitLevel) return NO_VIOLATIONS;
+		if (n === void 0 || n !== implicitLevel) return VALID_RESULT;
 		return [{
 			valid: false,
 			fixable: true,
@@ -2285,7 +2339,7 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		}];
 	}
 	static #checkNameProhibitedRoles({ props, effectiveRole }) {
-		if (!effectiveRole || effectiveRole === "none" || effectiveRole === "presentation" || !NAME_PROHIBITED_ROLES.has(effectiveRole)) return NO_VIOLATIONS;
+		if (!effectiveRole || effectiveRole === "none" || effectiveRole === "presentation" || !NAME_PROHIBITED_ROLES.has(effectiveRole)) return VALID_RESULT;
 		const results = [];
 		for (const key of NAME_PROHIBITED_ATTRIBUTES) {
 			if (!(key in props)) continue;
@@ -2301,9 +2355,9 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		return results;
 	}
 	static #checkNameRequiredRoles({ tag, props, effectiveRole }) {
-		if (!effectiveRole || !NAME_REQUIRED_ROLES.has(effectiveRole)) return NO_VIOLATIONS;
-		if ("aria-label" in props || "aria-labelledby" in props) return NO_VIOLATIONS;
-		if (tag === "img" && typeof props.alt === "string" && props.alt.length > 0) return NO_VIOLATIONS;
+		if (!effectiveRole || !NAME_REQUIRED_ROLES.has(effectiveRole)) return VALID_RESULT;
+		if ("aria-label" in props || "aria-labelledby" in props) return VALID_RESULT;
+		if (tag === "img" && isString(props.alt) && props.alt.length > 0) return VALID_RESULT;
 		return [{
 			valid: false,
 			fixable: false,
@@ -2316,12 +2370,12 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		diagnosticFor: (attribute, role) => AriaDiagnostics.requiredProperty(attribute, role)
 	};
 	static #checkRequiredAriaProperties(context) {
-		if (!isNonNull(context.props.role)) return NO_VIOLATIONS;
+		if (!isNonNull(context.props.role)) return VALID_RESULT;
 		return checkRequiredAttributes(AriaPolicyEngine.#requiredAriaPropertiesRule, context);
 	}
 	static #checkAriaHiddenOnFocusable({ tag, props }) {
-		if (props["aria-hidden"] !== "true" && props["aria-hidden"] !== true) return NO_VIOLATIONS;
-		if (!isPotentiallyFocusable(tag, props)) return NO_VIOLATIONS;
+		if (props["aria-hidden"] !== "true" && props["aria-hidden"] !== true) return VALID_RESULT;
+		if (!isPotentiallyFocusable(tag, props)) return VALID_RESULT;
 		return [{
 			valid: false,
 			fixable: false,
@@ -2331,7 +2385,7 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		}];
 	}
 	static #checkPresentationalAriaAttributes({ tag, props, effectiveRole }) {
-		if (effectiveRole !== "none" && effectiveRole !== "presentation") return NO_VIOLATIONS;
+		if (effectiveRole !== "none" && effectiveRole !== "presentation") return VALID_RESULT;
 		const results = [];
 		iterate.forEachEntry(props, (key) => {
 			if (!key.startsWith("aria-")) return;
@@ -2348,10 +2402,10 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 		return results;
 	}
 	static #checkMissingLiveRegion({ effectiveRole, props }) {
-		if (!effectiveRole) return NO_VIOLATIONS;
+		if (!effectiveRole) return VALID_RESULT;
 		const impliedLive = LIVE_REGION_ROLES.get(effectiveRole);
-		if (!impliedLive) return NO_VIOLATIONS;
-		if ("aria-live" in props) return NO_VIOLATIONS;
+		if (!impliedLive) return VALID_RESULT;
+		if ("aria-live" in props) return VALID_RESULT;
 		return [{
 			valid: false,
 			fixable: true,
@@ -2391,8 +2445,8 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 	};
 	static #checkInvalidAriaRelevant({ props }) {
 		const relevant = props["aria-relevant"];
-		if (relevant === void 0) return NO_VIOLATIONS;
-		if (typeof relevant !== "string") return NO_VIOLATIONS;
+		if (isUndefined(relevant)) return VALID_RESULT;
+		if (!isString(relevant)) return VALID_RESULT;
 		const tokens = relevant.trim().split(/\s+/);
 		const invalid = tokens.filter((t) => !VALID_RELEVANT_TOKENS.has(t));
 		if (invalid.length > 0) return [{
@@ -2411,7 +2465,7 @@ var AriaPolicyEngine = class AriaPolicyEngine extends InvariantBase {
 			diagnostic: AriaDiagnostics.relevantSuperseded(),
 			fix: AriaPolicyEngine.#normalizeRelevantAllFix
 		}];
-		return NO_VIOLATIONS;
+		return VALID_RESULT;
 	}
 };
 //#endregion
@@ -4978,9 +5032,10 @@ const PREACT_FIELD_VALIDATORS = {
 	filterProps: (v) => v === void 0 || isFunction(v)
 };
 /**
-* Type guard narrowing the generic `FactoryOptions` shape down to
-* `PreactFactoryOptions` — the type `buildRuntime` is declared against. See
-* `isFactoryOptionsLike` for what this does and doesn't validate.
+* Type guard narrowing a concrete contract `C` down to `C & PreactFactoryOptions` — the type
+* `buildRuntime` is declared against. Single-generic, matching `createContractComponent`'s own
+* `C extends PreactFactoryOptions` (Phase 2 of the `defineContract` refactor — was 5 independent
+* generics). See `isFactoryOptionsLike` for what this does and doesn't validate.
 */
 function isPreactFactoryOptions(options) {
 	return isFactoryOptionsLike(options, PREACT_FIELD_VALIDATORS);
@@ -5007,9 +5062,21 @@ function isPreactFactoryOptions(options) {
 * Returns a `forwardRef` component — `ref` is forwarded to the rendered host element. Pass
 * `subComponents` to attach named sub-components (`Card.Header`) and `onElement` to run setup
 * once the real DOM element exists.
+*
+* `TDefault`/`Props`/`Variants`/`TPreset`/`TPlugin` are each `ContractXOf<C>`-derived *defaults*
+* on this function's own type parameter list, mirroring `@praxis-kit/react`'s identical fix — see
+* that adapter's own doc comment for why (computed as function type-parameter defaults, not inline
+* body computations, which doesn't resolve for a still-abstract `C`). No `TAllowed` here, matching
+* this adapter's pre-refactor behavior — Preact never threaded it as its own generic.
 */
 function createContractComponent(options) {
 	invariant(isPreactFactoryOptions(options), "options is not a valid PreactFactoryOptions object");
+	/**
+	* `C` and `TDefault`/`Props`/`Variants`/`TPreset` are formally independent type parameters to
+	* the checker — see `@praxis-kit/react`'s identical comment for the full explanation. The
+	* `invariant` above is what actually guarantees `options` is `PreactFactoryOptions` shaped; this
+	* assertion bridges the gap in the compiler's reasoning.
+	*/
 	const bundle = buildRuntime(options);
 	const { onElement } = options;
 	const Component = forwardRef(function Component(props, ref) {
@@ -5040,4 +5107,4 @@ function createContractComponent(options) {
 	return assembled;
 }
 //#endregion
-export { Slottable, createContractComponent, defineContractComponent };
+export { Slottable, createContractComponent };