@alexkroman1/aai-ui 6.7.1 → 6.7.2

package/dist/components/_form-readiness.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Whether a form's own fields exist yet.
+ *
+ * `<Form>` leans entirely on NATIVE validation — it is a real `<form>` with no
+ * `noValidate`, so a `required` field is what stops an empty submit, and the
+ * module doc next door says so. That has one hole, and it is the whole reason
+ * this exists: a field set declared REMOTELY is not in the DOM while its
+ * declaration is in flight, so there is nothing for the browser to validate and
+ * an empty submit sails through.
+ *
+ * It is not theoretical. `<WorkflowFields>` renders `null` until the workflow
+ * listing lands, so the transcription desk's first click — before the one-request
+ * lookup answered — submitted a form holding only its button. The browser was
+ * happy, the payload was `{}`, and the run was refused by the agent with
+ * `Invalid input for workflow "transcribeStream": recording: Invalid input`: a
+ * schema complaint about a field the person had not been shown, naming a workflow
+ * they did not choose by name, for a file picker that appeared a moment later.
+ *
+ * ## Readiness is DECLARED by the children, because only they know
+ *
+ * `Form` cannot ask. It renders `{children}` and reads the DOM on submit, and a
+ * pending fetch leaves no trace in the DOM at all — which is exactly the
+ * difference from `data-aai-read`, the other thing a child tells the form: that
+ * one describes an element that EXISTS. So this is a context rather than an
+ * attribute, and it carries the one fact a DOM read cannot recover.
+ *
+ * A form with no such children is ready by definition — `useFormFieldsPending`
+ * outside a provider reports nothing pending, so every hand-written form is
+ * unaffected and `Form` keeps working outside this package.
+ */
+/** What a child calls to say whether its own fields are ready. */
+type Readiness = (key: string, pending: boolean) => void;
+export declare const FormReadinessProvider: import("react").Provider<Readiness | undefined>;
+/**
+ * Track which children are still waiting for their fields.
+ *
+ * A SET keyed by the child's own `useId`, not a counter: a child that re-renders
+ * while pending must not increment twice, and one that unmounts mid-flight must
+ * not leave the form disabled forever. Both are the ordinary lifecycle here — a
+ * page that switches workflows swaps one `<WorkflowFields>` for another.
+ */
+export declare function useFormReadiness(): {
+    pending: boolean;
+    declare: Readiness;
+};
+/**
+ * Declare from a child that its fields are, or are no longer, still loading.
+ *
+ * Reports through an EFFECT rather than during render, because this writes to a
+ * parent's state — doing it in the render body is the "cannot update a component
+ * while rendering a different component" warning, and under StrictMode it is a
+ * double report the parent has to be idempotent about anyway. The cleanup
+ * releases the claim, so an unmounted field set never holds the form shut.
+ */
+export declare function useDeclareFieldsPending(pending: boolean): void;
+export {};

package/dist/index.js

@@ -14,12 +14,98 @@ import { client, mountRoot, resolveContainer } from "./define-client.js";
 import { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.js";
 import clsx from "clsx";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { createElement, useCallback, useEffect, useId, useRef, useState } from "react";
+import { createContext, createElement, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
 import { errorMessage, isTerminal, isTerminal as isTerminal$1 } from "@alexkroman1/aai";
 import { isRecord, omitUndefined, safeJsonParse as safeJsonParse$1 } from "@alexkroman1/aai/utils";
 import { createWorkflowApiClient } from "@alexkroman1/aai/workflow-api";
 import { createParser } from "eventsource-parser";
 import { createEpoch } from "@alexkroman1/aai/internal";
+//#region components/_form-readiness.ts
+/**
+* Whether a form's own fields exist yet.
+*
+* `<Form>` leans entirely on NATIVE validation — it is a real `<form>` with no
+* `noValidate`, so a `required` field is what stops an empty submit, and the
+* module doc next door says so. That has one hole, and it is the whole reason
+* this exists: a field set declared REMOTELY is not in the DOM while its
+* declaration is in flight, so there is nothing for the browser to validate and
+* an empty submit sails through.
+*
+* It is not theoretical. `<WorkflowFields>` renders `null` until the workflow
+* listing lands, so the transcription desk's first click — before the one-request
+* lookup answered — submitted a form holding only its button. The browser was
+* happy, the payload was `{}`, and the run was refused by the agent with
+* `Invalid input for workflow "transcribeStream": recording: Invalid input`: a
+* schema complaint about a field the person had not been shown, naming a workflow
+* they did not choose by name, for a file picker that appeared a moment later.
+*
+* ## Readiness is DECLARED by the children, because only they know
+*
+* `Form` cannot ask. It renders `{children}` and reads the DOM on submit, and a
+* pending fetch leaves no trace in the DOM at all — which is exactly the
+* difference from `data-aai-read`, the other thing a child tells the form: that
+* one describes an element that EXISTS. So this is a context rather than an
+* attribute, and it carries the one fact a DOM read cannot recover.
+*
+* A form with no such children is ready by definition — `useFormFieldsPending`
+* outside a provider reports nothing pending, so every hand-written form is
+* unaffected and `Form` keeps working outside this package.
+*/
+/**
+* Set by `Form`, read by any field set that fetches its own declaration.
+*
+* `undefined` means no `Form` above, which is legal: the fields render, they are
+* simply not gating anything.
+*/
+const FormReadinessContext = createContext(void 0);
+const FormReadinessProvider = FormReadinessContext.Provider;
+/**
+* Track which children are still waiting for their fields.
+*
+* A SET keyed by the child's own `useId`, not a counter: a child that re-renders
+* while pending must not increment twice, and one that unmounts mid-flight must
+* not leave the form disabled forever. Both are the ordinary lifecycle here — a
+* page that switches workflows swaps one `<WorkflowFields>` for another.
+*/
+function useFormReadiness() {
+	const [waiting, setWaiting] = useState(() => /* @__PURE__ */ new Set());
+	const declare = useCallback((key, pending) => {
+		setWaiting((held) => {
+			if (pending === held.has(key)) return held;
+			const next = new Set(held);
+			if (pending) next.add(key);
+			else next.delete(key);
+			return next;
+		});
+	}, []);
+	return {
+		pending: waiting.size > 0,
+		declare
+	};
+}
+/**
+* Declare from a child that its fields are, or are no longer, still loading.
+*
+* Reports through an EFFECT rather than during render, because this writes to a
+* parent's state — doing it in the render body is the "cannot update a component
+* while rendering a different component" warning, and under StrictMode it is a
+* double report the parent has to be idempotent about anyway. The cleanup
+* releases the claim, so an unmounted field set never holds the form shut.
+*/
+function useDeclareFieldsPending(pending) {
+	const declare = useContext(FormReadinessContext);
+	const key = useId();
+	useEffect(() => {
+		if (!declare) return;
+		declare(key, pending);
+		return () => declare(key, false);
+	}, [
+		declare,
+		key,
+		pending
+	]);
+}
+//#endregion
 //#region components/_form-values.ts
 /**
 * Read one `<form>`'s named controls into a plain object.
@@ -172,10 +258,11 @@ function dataUrl(file) {
 function Form({ onSubmit, error, children, className, ...rest }) {
 	const theme = useTheme();
 	const [busy, setBusy] = useState(false);
+	const { pending: fieldsPending, declare } = useFormReadiness();
 	return /* @__PURE__ */ jsxs("form", {
 		onSubmit: useCallback((event) => {
 			event.preventDefault();
-			if (busy) return;
+			if (busy || fieldsPending) return;
 			const form = event.currentTarget;
 			setBusy(true);
 			(async () => {
@@ -185,13 +272,20 @@ function Form({ onSubmit, error, children, className, ...rest }) {
 					setBusy(false);
 				}
 			})();
-		}, [busy, onSubmit]),
+		}, [
+			busy,
+			fieldsPending,
+			onSubmit
+		]),
 		className: clsx("flex flex-col gap-5 font-aai", className),
 		...rest,
 		children: [/* @__PURE__ */ jsx("fieldset", {
-			disabled: busy,
+			disabled: busy || fieldsPending,
 			className: "contents",
-			children
+			children: /* @__PURE__ */ jsx(FormReadinessProvider, {
+				value: declare,
+				children
+			})
 		}), error !== void 0 && error !== "" && /* @__PURE__ */ jsx("p", {
 			role: "alert",
 			className: "text-sm",
@@ -1234,8 +1328,9 @@ function useWorkflowSubmit(workflow, opts = {}) {
 * @public
 */
 function WorkflowFields({ workflow }) {
-	const { workflows } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
+	const { workflows, loading } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
 	const summary = typeof workflow === "string" ? workflows.find((entry) => entry.name === workflow) : workflow;
+	useDeclareFieldsPending(loading);
 	const schema = asObjectSchema(summary?.inputSchema);
 	if (!schema?.properties) return null;
 	const required = new Set(schema.required ?? []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "6.7.1",
+  "version": "6.7.2",
   "type": "module",
   "files": [
     "dist",
@@ -29,7 +29,7 @@
     "remark-gfm": "^4.0.1",
     "use-stick-to-bottom": "^1.1.6",
     "use-sync-external-store": "^1.6.0",
-    "@alexkroman1/aai": "6.7.1"
+    "@alexkroman1/aai": "6.7.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",