@ai-gui/plugin-form 0.11.1 → 0.12.0

package/dist/index.cjs

@@ -393,7 +393,12 @@ function mountForm(host, definition, options) {
 		for (const element of Array.from(formElement.elements)) if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement || element instanceof HTMLButtonElement || element instanceof HTMLFieldSetElement) element.disabled = true;
 		submit.textContent = options.submittedLabel ?? "Submitted";
 	};
-	if (submitted) markSubmitted();
+	const stored = options.restore?.(definition.id);
+	if (stored) {
+		writeControls(definition, controls, stored.values);
+		markSubmitted();
+		applyOutcome(stored.outcome, gradeAgainstExpectations(stored.values));
+	} else if (submitted) markSubmitted();
 	const onInput = (event) => {
 		const control = event.target;
 		if (!(control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement || control instanceof HTMLSelectElement)) return;
@@ -429,6 +434,14 @@ function mountForm(host, definition, options) {
 		}).then((result) => {
 			markSubmitted();
 			applyOutcome(result, graded);
+			if (disposed) return;
+			const outcome = (0, __ai_gui_core.actionOutcome)(result) ?? graded;
+			try {
+				options.onSubmitted?.(definition.id, {
+					values: validation.values,
+					...outcome ? { outcome } : {}
+				});
+			} catch {}
 		}, (error) => {
 			if (!disposed && !controller.signal.aborted) {
 				actionError.textContent = actionErrorMessage(error);
@@ -545,6 +558,26 @@ function readControls(definition, controls) {
 	}
 	return values;
 }
+/**
+* Put a stored submission back into the controls — the inverse of `readControls`.
+*
+* A radio group is several inputs sharing a name, and `controls` holds only the first, so the one
+* that carries the stored value has to be found in the group. Setting `.value` on that first input
+* would rename the option instead of choosing it.
+*/
+function writeControls(definition, controls, values) {
+	for (const field of definition.fields) {
+		const control = controls.get(field.name);
+		const value = values[field.name];
+		if (!control || value === void 0) continue;
+		if (field.type === "checkbox" && control instanceof HTMLInputElement) control.checked = value === true;
+		else if (field.type === "radio") {
+			const group = control.form?.elements.namedItem(field.name);
+			const inputs = group instanceof RadioNodeList ? Array.from(group) : [control];
+			for (const input of inputs) if (input instanceof HTMLInputElement) input.checked = input.value === String(value);
+		} else control.value = String(value);
+	}
+}
 function renderErrors(errors, controls, elements) {
 	for (const name of controls.keys()) {
 		const message = errors[name];

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AIGuiPlugin, ActionRuntime } from "@ai-gui/core";
+import { AIGuiPlugin, ActionOutcome, ActionRuntime } from "@ai-gui/core";
 
 //#region src/index.d.ts
 type FormFieldType = "text" | "textarea" | "number" | "date" | "select" | "checkbox" | "radio";
@@ -62,16 +62,43 @@ interface FormValidationResult {
   values: Record<string, string | number | boolean>;
   errors: Record<string, string>;
 }
+/** What was answered, and how it turned out — enough to put a form back the way it was left. */
+interface FormSubmission {
+  values: Record<string, string | number | boolean>;
+  /**
+   * The verdict, when the host kept one. Omitted, the fields' own `expect` is graded again, so a
+   * quiz still comes back coloured without the host having to store the marking.
+   */
+  outcome?: ActionOutcome;
+}
 interface FormPluginOptions {
   /** Shared core runtime whose registry is the only allowlist for submitAction. */
   actionRuntime: ActionRuntime;
-  /** Mount forms as already submitted, useful when restoring persisted conversations. */
+  /** Mount every form as already submitted, useful when restoring persisted conversations. */
   submitted?: boolean;
   /** Label shown after a successful or restored submission. */
   submittedLabel?: string;
+  /**
+   * The submission this form already has, by form id.
+   *
+   * `submitted` on its own marks a form done without saying what was answered, so a reloaded
+   * conversation shows a disabled question with nothing chosen in it — which reads as worse than
+   * unanswered, since it claims to have been answered and cannot say with what. Returning the
+   * values puts the person's own answer back in front of them.
+   *
+   * Called once per form as it mounts, so it can read whatever the host has loaded by then.
+   */
+  restore?: (formId: string) => FormSubmission | undefined;
+  /**
+   * Called when a submission succeeds, so the host can persist what to restore later.
+   *
+   * The action handler sees the values too, but not which form they came from — the form id is only
+   * in `cardType`, which a host would have to parse. This hands it over directly.
+   */
+  onSubmitted?: (formId: string, submission: FormSubmission) => void;
 }
 declare function formPromptSpec(): string;
 declare function form(options: FormPluginOptions): AIGuiPlugin;
 declare function parseFormDefinition(source: string): FormParseResult;
 declare function validateFormValues(definition: FormDefinition, input: Record<string, unknown>): FormValidationResult; //#endregion
-export { FormCheckboxField, FormChoiceField, FormDateField, FormDefinition, FormField, FormFieldType, FormNumberField, FormOption, FormParseResult, FormPluginOptions, FormStringField, FormValidationResult, form, formPromptSpec, parseFormDefinition, validateFormValues };
+export { FormCheckboxField, FormChoiceField, FormDateField, FormDefinition, FormField, FormFieldType, FormNumberField, FormOption, FormParseResult, FormPluginOptions, FormStringField, FormSubmission, FormValidationResult, form, formPromptSpec, parseFormDefinition, validateFormValues };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AIGuiPlugin, ActionRuntime } from "@ai-gui/core";
+import { AIGuiPlugin, ActionOutcome, ActionRuntime } from "@ai-gui/core";
 
 //#region src/index.d.ts
 type FormFieldType = "text" | "textarea" | "number" | "date" | "select" | "checkbox" | "radio";
@@ -62,16 +62,43 @@ interface FormValidationResult {
   values: Record<string, string | number | boolean>;
   errors: Record<string, string>;
 }
+/** What was answered, and how it turned out — enough to put a form back the way it was left. */
+interface FormSubmission {
+  values: Record<string, string | number | boolean>;
+  /**
+   * The verdict, when the host kept one. Omitted, the fields' own `expect` is graded again, so a
+   * quiz still comes back coloured without the host having to store the marking.
+   */
+  outcome?: ActionOutcome;
+}
 interface FormPluginOptions {
   /** Shared core runtime whose registry is the only allowlist for submitAction. */
   actionRuntime: ActionRuntime;
-  /** Mount forms as already submitted, useful when restoring persisted conversations. */
+  /** Mount every form as already submitted, useful when restoring persisted conversations. */
   submitted?: boolean;
   /** Label shown after a successful or restored submission. */
   submittedLabel?: string;
+  /**
+   * The submission this form already has, by form id.
+   *
+   * `submitted` on its own marks a form done without saying what was answered, so a reloaded
+   * conversation shows a disabled question with nothing chosen in it — which reads as worse than
+   * unanswered, since it claims to have been answered and cannot say with what. Returning the
+   * values puts the person's own answer back in front of them.
+   *
+   * Called once per form as it mounts, so it can read whatever the host has loaded by then.
+   */
+  restore?: (formId: string) => FormSubmission | undefined;
+  /**
+   * Called when a submission succeeds, so the host can persist what to restore later.
+   *
+   * The action handler sees the values too, but not which form they came from — the form id is only
+   * in `cardType`, which a host would have to parse. This hands it over directly.
+   */
+  onSubmitted?: (formId: string, submission: FormSubmission) => void;
 }
 declare function formPromptSpec(): string;
 declare function form(options: FormPluginOptions): AIGuiPlugin;
 declare function parseFormDefinition(source: string): FormParseResult;
 declare function validateFormValues(definition: FormDefinition, input: Record<string, unknown>): FormValidationResult; //#endregion
-export { FormCheckboxField, FormChoiceField, FormDateField, FormDefinition, FormField, FormFieldType, FormNumberField, FormOption, FormParseResult, FormPluginOptions, FormStringField, FormValidationResult, form, formPromptSpec, parseFormDefinition, validateFormValues };
+export { FormCheckboxField, FormChoiceField, FormDateField, FormDefinition, FormField, FormFieldType, FormNumberField, FormOption, FormParseResult, FormPluginOptions, FormStringField, FormSubmission, FormValidationResult, form, formPromptSpec, parseFormDefinition, validateFormValues };

package/dist/index.js

@@ -369,7 +369,12 @@ function mountForm(host, definition, options) {
 		for (const element of Array.from(formElement.elements)) if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement || element instanceof HTMLButtonElement || element instanceof HTMLFieldSetElement) element.disabled = true;
 		submit.textContent = options.submittedLabel ?? "Submitted";
 	};
-	if (submitted) markSubmitted();
+	const stored = options.restore?.(definition.id);
+	if (stored) {
+		writeControls(definition, controls, stored.values);
+		markSubmitted();
+		applyOutcome(stored.outcome, gradeAgainstExpectations(stored.values));
+	} else if (submitted) markSubmitted();
 	const onInput = (event) => {
 		const control = event.target;
 		if (!(control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement || control instanceof HTMLSelectElement)) return;
@@ -405,6 +410,14 @@ function mountForm(host, definition, options) {
 		}).then((result) => {
 			markSubmitted();
 			applyOutcome(result, graded);
+			if (disposed) return;
+			const outcome = actionOutcome(result) ?? graded;
+			try {
+				options.onSubmitted?.(definition.id, {
+					values: validation.values,
+					...outcome ? { outcome } : {}
+				});
+			} catch {}
 		}, (error) => {
 			if (!disposed && !controller.signal.aborted) {
 				actionError.textContent = actionErrorMessage(error);
@@ -521,6 +534,26 @@ function readControls(definition, controls) {
 	}
 	return values;
 }
+/**
+* Put a stored submission back into the controls — the inverse of `readControls`.
+*
+* A radio group is several inputs sharing a name, and `controls` holds only the first, so the one
+* that carries the stored value has to be found in the group. Setting `.value` on that first input
+* would rename the option instead of choosing it.
+*/
+function writeControls(definition, controls, values) {
+	for (const field of definition.fields) {
+		const control = controls.get(field.name);
+		const value = values[field.name];
+		if (!control || value === void 0) continue;
+		if (field.type === "checkbox" && control instanceof HTMLInputElement) control.checked = value === true;
+		else if (field.type === "radio") {
+			const group = control.form?.elements.namedItem(field.name);
+			const inputs = group instanceof RadioNodeList ? Array.from(group) : [control];
+			for (const input of inputs) if (input instanceof HTMLInputElement) input.checked = input.value === String(value);
+		} else control.value = String(value);
+	}
+}
 function renderErrors(errors, controls, elements) {
 	for (const name of controls.keys()) {
 		const message = errors[name];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-gui/plugin-form",
-  "version": "0.11.1",
+  "version": "0.12.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.11.1"
+    "@ai-gui/core": "0.12.0"
   },
   "scripts": {
     "build": "tsdown",