@ai-gui/plugin-form 0.6.2 → 0.8.0

package/dist/index.cjs

@@ -51,7 +51,8 @@ const FIELD_KEYS = new Set([
 	"min",
 	"max",
 	"options",
-	"placeholder"
+	"placeholder",
+	"expect"
 ]);
 const OPTION_KEYS = new Set(["label", "value"]);
 const SAFE_NAME = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
@@ -232,12 +233,16 @@ function parseField(value, index, issues) {
 			issues.push(`${path}.pattern must be a valid regular expression.`);
 		}
 	}
+	let expected;
+	if (value.expect !== void 0) if (typeof value.expect === "string" || typeof value.expect === "number" || typeof value.expect === "boolean") expected = value.expect;
+	else issues.push(`${path}.expect must be a string, a number, or a boolean.`);
 	if (!name || !label || !type) return void 0;
 	const base = {
 		name,
 		label,
 		...value.required === true ? { required: true } : {},
-		...placeholder === void 0 ? {} : { placeholder }
+		...placeholder === void 0 ? {} : { placeholder },
+		...expected === void 0 ? {} : { expect: expected }
 	};
 	if (type === "number") {
 		if (minLength !== void 0 || maxLength !== void 0 || pattern !== void 0 || value.options !== void 0) issues.push(`${path} contains constraints unsupported by number fields.`);
@@ -318,22 +323,67 @@ function mountForm(host, definition, options) {
 	formElement.setAttribute("data-aigui-form-instance", instanceId);
 	const controls = new Map();
 	const errorElements = new Map();
+	const fieldContainers = new Map();
 	for (const field of definition.fields) {
 		const rendered = createField(instancePrefix, field);
 		formElement.appendChild(rendered.container);
 		controls.set(field.name, rendered.control);
 		errorElements.set(field.name, rendered.error);
+		fieldContainers.set(field.name, rendered.container);
 	}
 	const actionError = document.createElement("div");
 	actionError.setAttribute("data-aigui-form-action-error", "");
 	actionError.setAttribute("role", "alert");
 	actionError.hidden = true;
 	formElement.appendChild(actionError);
+	const outcomeMessage = document.createElement("div");
+	outcomeMessage.setAttribute("data-aigui-form-outcome-message", "");
+	outcomeMessage.setAttribute("aria-live", "polite");
+	outcomeMessage.hidden = true;
+	formElement.appendChild(outcomeMessage);
 	const submit = document.createElement("button");
 	submit.type = "button";
 	submit.setAttribute("data-aigui-form-submit", "");
 	submit.textContent = definition.submitLabel ?? "Submit";
 	formElement.appendChild(submit);
+	/**
+	* Compare the submission with the answers the fields declared.
+	*
+	* Only fields carrying `expect` take part, so a plain form is never marked. The tone is the worst
+	* of them: one wrong answer among three right ones is not a pass.
+	*/
+	const gradeAgainstExpectations = (values) => {
+		const graded = definition.fields.filter((field) => field.expect !== void 0);
+		if (graded.length === 0) return void 0;
+		const fieldTones = {};
+		let wrong = 0;
+		for (const field of graded) {
+			const submitted$1 = values[field.name];
+			const matches = typeof field.expect === "string" && typeof submitted$1 === "string" ? submitted$1.trim() === field.expect.trim() : submitted$1 === field.expect;
+			fieldTones[field.name] = matches ? "positive" : "warning";
+			if (!matches) wrong += 1;
+		}
+		return {
+			tone: wrong === 0 ? "positive" : "warning",
+			fields: fieldTones
+		};
+	};
+	/**
+	* Show how the submission turned out, when the handler judged it.
+	*
+	* The result used to be discarded, so an app that knew the answer was wrong had no way to say so
+	* — the form simply disabled itself and read "Submitted" whether the answer was right or not.
+	*/
+	const applyOutcome = (result, fallback) => {
+		const outcome = (0, __ai_gui_core.actionOutcome)(result) ?? fallback;
+		if (!outcome || disposed) return;
+		formElement.setAttribute("data-aigui-form-outcome", outcome.tone);
+		if (outcome.message) {
+			outcomeMessage.textContent = outcome.message;
+			outcomeMessage.hidden = false;
+		}
+		for (const [name, tone] of Object.entries(outcome.fields ?? {})) fieldContainers.get(name)?.setAttribute("data-aigui-form-field-outcome", tone);
+	};
 	const markSubmitted = () => {
 		if (disposed) return;
 		pending = false;
@@ -362,6 +412,7 @@ function mountForm(host, definition, options) {
 		pending = true;
 		submit.disabled = true;
 		formElement.setAttribute("aria-busy", "true");
+		const graded = gradeAgainstExpectations(validation.values);
 		const settle = () => {
 			if (disposed) return;
 			pending = false;
@@ -375,7 +426,10 @@ function mountForm(host, definition, options) {
 		}, {
 			owner,
 			signal: controller.signal
-		}).then(markSubmitted, (error) => {
+		}).then((result) => {
+			markSubmitted();
+			applyOutcome(result, graded);
+		}, (error) => {
 			if (!disposed && !controller.signal.aborted) {
 				actionError.textContent = actionErrorMessage(error);
 				actionError.hidden = false;

package/dist/index.d.cts

@@ -12,6 +12,15 @@ interface FormFieldBase {
   label: string;
   required?: boolean;
   placeholder?: string;
+  /**
+   * The answer this field is expected to carry.
+   *
+   * Declaring it lets the form report how the submission compared — a quiz colours itself the
+   * moment it is answered instead of waiting for a round trip to say so. Unlike the constraints
+   * beside it this never blocks a submission: a wrong answer is an answer, and the person is told
+   * rather than stopped.
+   */
+  expect?: string | number | boolean;
 }
 interface FormStringField extends FormFieldBase {
   type: "text" | "textarea";

package/dist/index.d.ts

@@ -12,6 +12,15 @@ interface FormFieldBase {
   label: string;
   required?: boolean;
   placeholder?: string;
+  /**
+   * The answer this field is expected to carry.
+   *
+   * Declaring it lets the form report how the submission compared — a quiz colours itself the
+   * moment it is answered instead of waiting for a round trip to say so. Unlike the constraints
+   * beside it this never blocks a submission: a wrong answer is an answer, and the person is told
+   * rather than stopped.
+   */
+  expect?: string | number | boolean;
 }
 interface FormStringField extends FormFieldBase {
   type: "text" | "textarea";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ActionRuntimeError } from "@ai-gui/core";
+import { ActionRuntimeError, actionOutcome } from "@ai-gui/core";
 
 //#region src/index.ts
 const FIELD_TYPES = new Set([
@@ -27,7 +27,8 @@ const FIELD_KEYS = new Set([
 	"min",
 	"max",
 	"options",
-	"placeholder"
+	"placeholder",
+	"expect"
 ]);
 const OPTION_KEYS = new Set(["label", "value"]);
 const SAFE_NAME = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
@@ -208,12 +209,16 @@ function parseField(value, index, issues) {
 			issues.push(`${path}.pattern must be a valid regular expression.`);
 		}
 	}
+	let expected;
+	if (value.expect !== void 0) if (typeof value.expect === "string" || typeof value.expect === "number" || typeof value.expect === "boolean") expected = value.expect;
+	else issues.push(`${path}.expect must be a string, a number, or a boolean.`);
 	if (!name || !label || !type) return void 0;
 	const base = {
 		name,
 		label,
 		...value.required === true ? { required: true } : {},
-		...placeholder === void 0 ? {} : { placeholder }
+		...placeholder === void 0 ? {} : { placeholder },
+		...expected === void 0 ? {} : { expect: expected }
 	};
 	if (type === "number") {
 		if (minLength !== void 0 || maxLength !== void 0 || pattern !== void 0 || value.options !== void 0) issues.push(`${path} contains constraints unsupported by number fields.`);
@@ -294,22 +299,67 @@ function mountForm(host, definition, options) {
 	formElement.setAttribute("data-aigui-form-instance", instanceId);
 	const controls = new Map();
 	const errorElements = new Map();
+	const fieldContainers = new Map();
 	for (const field of definition.fields) {
 		const rendered = createField(instancePrefix, field);
 		formElement.appendChild(rendered.container);
 		controls.set(field.name, rendered.control);
 		errorElements.set(field.name, rendered.error);
+		fieldContainers.set(field.name, rendered.container);
 	}
 	const actionError = document.createElement("div");
 	actionError.setAttribute("data-aigui-form-action-error", "");
 	actionError.setAttribute("role", "alert");
 	actionError.hidden = true;
 	formElement.appendChild(actionError);
+	const outcomeMessage = document.createElement("div");
+	outcomeMessage.setAttribute("data-aigui-form-outcome-message", "");
+	outcomeMessage.setAttribute("aria-live", "polite");
+	outcomeMessage.hidden = true;
+	formElement.appendChild(outcomeMessage);
 	const submit = document.createElement("button");
 	submit.type = "button";
 	submit.setAttribute("data-aigui-form-submit", "");
 	submit.textContent = definition.submitLabel ?? "Submit";
 	formElement.appendChild(submit);
+	/**
+	* Compare the submission with the answers the fields declared.
+	*
+	* Only fields carrying `expect` take part, so a plain form is never marked. The tone is the worst
+	* of them: one wrong answer among three right ones is not a pass.
+	*/
+	const gradeAgainstExpectations = (values) => {
+		const graded = definition.fields.filter((field) => field.expect !== void 0);
+		if (graded.length === 0) return void 0;
+		const fieldTones = {};
+		let wrong = 0;
+		for (const field of graded) {
+			const submitted$1 = values[field.name];
+			const matches = typeof field.expect === "string" && typeof submitted$1 === "string" ? submitted$1.trim() === field.expect.trim() : submitted$1 === field.expect;
+			fieldTones[field.name] = matches ? "positive" : "warning";
+			if (!matches) wrong += 1;
+		}
+		return {
+			tone: wrong === 0 ? "positive" : "warning",
+			fields: fieldTones
+		};
+	};
+	/**
+	* Show how the submission turned out, when the handler judged it.
+	*
+	* The result used to be discarded, so an app that knew the answer was wrong had no way to say so
+	* — the form simply disabled itself and read "Submitted" whether the answer was right or not.
+	*/
+	const applyOutcome = (result, fallback) => {
+		const outcome = actionOutcome(result) ?? fallback;
+		if (!outcome || disposed) return;
+		formElement.setAttribute("data-aigui-form-outcome", outcome.tone);
+		if (outcome.message) {
+			outcomeMessage.textContent = outcome.message;
+			outcomeMessage.hidden = false;
+		}
+		for (const [name, tone] of Object.entries(outcome.fields ?? {})) fieldContainers.get(name)?.setAttribute("data-aigui-form-field-outcome", tone);
+	};
 	const markSubmitted = () => {
 		if (disposed) return;
 		pending = false;
@@ -338,6 +388,7 @@ function mountForm(host, definition, options) {
 		pending = true;
 		submit.disabled = true;
 		formElement.setAttribute("aria-busy", "true");
+		const graded = gradeAgainstExpectations(validation.values);
 		const settle = () => {
 			if (disposed) return;
 			pending = false;
@@ -351,7 +402,10 @@ function mountForm(host, definition, options) {
 		}, {
 			owner,
 			signal: controller.signal
-		}).then(markSubmitted, (error) => {
+		}).then((result) => {
+			markSubmitted();
+			applyOutcome(result, graded);
+		}, (error) => {
 			if (!disposed && !controller.signal.aborted) {
 				actionError.textContent = actionErrorMessage(error);
 				actionError.hidden = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-gui/plugin-form",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Safe interactive form blocks for AIGUI, backed by the core ActionRuntime.",
   "keywords": [
     "llm",
@@ -49,7 +49,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ai-gui/core": "0.6.2"
+    "@ai-gui/core": "0.8.0"
   },
   "scripts": {
     "build": "tsdown",