@theoremjs/react 0.3.4-next.548.gbb156b2 → 0.3.4-next.554.g84e62b0

package/README.md

@@ -275,7 +275,7 @@ import { TheoremDecision } from '@theoremjs/react/ui';
 <TheoremDecision endpoint="/api/decision" />
 ```
 
-- `questions` maps each question id to its definition.
+- `questions` maps each question id to its definition. When the questions depend on the decision, such as one question for each passage in the state, pass a builder instead (below).
 - `images` is optional. It holds pictures a decision can send, by reference, such as `<ghs02>` in "Which item matches <ghs02>?". The kernel sends only the ones that the state or a question references. The page sees them and refuses its own image under one of their names.
 - `vault` holds the keys of the profile, by slot.
 - `metadata` is optional. It adds data, such as the signed-in user, to the trace record of each decision.
@@ -292,7 +292,29 @@ Pass `onQuestion` to open a question where it is set up, such as in an editor. E
 
 Pass `questionText`, each question's text by its id, to show it under its answer's title, cut to two lines with the rest on hover. The page is never sent a question's instructions, so it shows only the text you give it.
 
-For your own UI, use `useTheoremDecision`. Its `decide(state, assets)` takes the images by reference.
+When the questions change from one decision to the next, `questions` can be a builder, `{ input?, build }`. `build({ state, input })` returns the questions of one decision. `input` is optional: a zod schema for what the page fills in beside the state. The handler checks the posted input against it before `build` runs, and refuses a decision whose input does not fit. `TheoremDecision` shows the input as a form above the state. Each answer shows the questions that the builder made for its decision:
+
+```ts
+import { z } from '@theoremjs/agents';
+import type { DecisionQuestionsBuilder } from '@theoremjs/web/server';
+
+const perPassage: DecisionQuestionsBuilder<{ topic: string }> = {
+  input: z.object({ topic: z.string() }),
+  build: ({ state, input }) =>
+    Object.fromEntries(
+      Object.keys((state as { passages: Record<string, string> }).passages).map((id) => [
+        id,
+        {
+          type: 'choice',
+          instructions: `Does state.passages.${id} speak to ${input.topic}?`,
+          criteria: { yes: 'It does.', no: 'It does not.' },
+        },
+      ]),
+    ),
+};
+```
+
+For your own UI, use `useTheoremDecision`. Its `decide(state, assets, input)` takes the images by reference, and the builder's input when the profile's interface has `build.input`. A result from a builder carries the `questions` it answers.
 
 ### Embedding
 

package/hooks/use-theorem-decision.d.ts

@@ -1,17 +1,18 @@
-import type { DecisionAsset, DecisionJson, DecisionResult } from '@theoremjs/agents';
-import type { ClientFailure, DecisionInterface, DecisionTransport } from '@theoremjs/web/client';
+import type { DecisionAsset, DecisionJson } from '@theoremjs/agents';
+import type { ClientFailure, DecisionInterface, DecisionReplyResult, DecisionTransport } from '@theoremjs/web/client';
 import { type OneCallState } from './use-one-call.ts';
 export type TheoremDecisionState = {
     /** The profile as the page sees it; null until the host describes it. */
     iface: DecisionInterface | null;
     /** Why the host could not describe the profile. */
     describeFailure: ClientFailure | null;
-} & OneCallState<'deciding', DecisionResult>;
+} & OneCallState<'deciding', DecisionReplyResult>;
 /**
  * One decision profile: describe it once, then `decide(state)` as often as
- * needed. A new decision aborts the one still running.
+ * needed. A new decision aborts the one still running. When the host builds its
+ * questions for each decision, `input` is what its builder takes (`iface.build.input`).
  */
 export declare function useTheoremDecision(transport: DecisionTransport): TheoremDecisionState & {
-    decide: (state: Exclude<DecisionJson, null>, assets?: Record<string, DecisionAsset>) => Promise<void>;
+    decide: (state: Exclude<DecisionJson, null>, assets?: Record<string, DecisionAsset>, input?: unknown) => Promise<void>;
     cancel: () => void;
 };

package/hooks/use-theorem-decision.js

@@ -1,9 +1,10 @@
 import { useDescribed } from "./use-described.js";
 import { useOneCall } from "./use-one-call.js";
-const decideWith = (transport, signal, state, assets) => transport.decide(state, signal, assets);
+const decideWith = (transport, signal, state, assets, input) => transport.decide(state, signal, assets, input);
 /**
  * One decision profile: describe it once, then `decide(state)` as often as
- * needed. A new decision aborts the one still running.
+ * needed. A new decision aborts the one still running. When the host builds its
+ * questions for each decision, `input` is what its builder takes (`iface.build.input`).
  */
 export function useTheoremDecision(transport) {
     const { iface, describeFailure } = useDescribed(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.3.4-next.548.gbb156b2",
+  "version": "0.3.4-next.554.g84e62b0",
   "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
   "license": "MIT",
   "type": "module",
@@ -55,13 +55,13 @@
     "recharts": "^3.10.1"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.7.1",
-    "@astryxdesign/theme-neutral": "0.7.1",
+    "@astryxdesign/core": "0.7.4",
+    "@astryxdesign/theme-neutral": "0.7.4",
     "@stylexjs/stylex": "0.19.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@theoremjs/agents": "^0.3.4-next.548.gbb156b2",
-    "@theoremjs/web": "^0.3.4-next.548.gbb156b2"
+    "@theoremjs/agents": "^0.3.4-next.554.g84e62b0",
+    "@theoremjs/web": "^0.3.4-next.554.g84e62b0"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {

package/ui/TheoremDecision.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Banner } from '@astryxdesign/core/Banner';
-import { createDecisionTransport, } from '@theoremjs/web/client';
+import { createDecisionTransport, missingFields, sampleFromSchema, } from '@theoremjs/web/client';
 import { useMemo, useRef, useState } from 'react';
 import { droppedImages, namedImages, stateFields, } from "../client/decision-images.js";
 import { useTheoremDecision } from "../hooks/use-theorem-decision.js";
@@ -9,6 +9,7 @@ import { TheoremDecisionAnswers } from "./DecisionAnswers.js";
 import { ImageDrop } from "./DecisionImages.js";
 import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
 import { PaneFailure, PaneLoading } from "./PaneState.js";
+import { SchemaFields } from "./SchemaFields.js";
 import { StateFields, StateImages } from "./StateFields.js";
 import { useTraceInspector } from "./TraceInspectorPanel.js";
 import { TheoremThemeProvider } from "./theme.js";
@@ -54,26 +55,32 @@ function useDecisionState(defaultState, maxStateBytes) {
     const shown = check.state === undefined ? 'json' : view;
     return { text, setText, check, shown, setView };
 }
-/** The state, as fields or JSON, and Decide. */
-function DecisionRequest({ form, iface, images, onImages, note, isRunning, onRun, onStop, }) {
+/** What the host's question builder takes beside the state, and the fields it still needs. */
+function useBuildInput(schema) {
+    const [input, setInput] = useState(() => schema ? sampleFromSchema(schema) : {});
+    const missing = schema ? missingFields(schema, input) : [];
+    return { schema, input, setInput, missing };
+}
+/** The builder's input, then the state, as fields or JSON, and Decide. */
+function DecisionRequest({ form, built, iface, images, onImages, note, isReady, isRunning, onRun, onStop, }) {
     const t = useLabels();
     const { text, setText, check, shown, setView } = form;
     const withImages = iface.questions.some((question) => question.type === 'box') || Object.keys(images).length > 0;
     const fields = shown === 'fields' ? check.state : undefined;
     const named = stateFields(fields);
-    return (_jsxs(RequestCard, { title: t('@theorem.decision.state'), view: shown, hasFields: check.state !== undefined, onView: setView, onRun: onRun, children: [fields !== undefined ? (_jsx(StateImages, { value: { images, onImages }, children: _jsx(StateFields, { label: t('@theorem.decision.state'), value: fields, onChange: (next) => {
+    return (_jsxs(RequestCard, { title: t('@theorem.decision.state'), view: shown, hasFields: check.state !== undefined, onView: setView, onRun: onRun, children: [built.schema ? (_jsx(SchemaFields, { schema: built.schema, value: built.input, onChange: built.setInput })) : null, fields !== undefined ? (_jsx(StateImages, { value: { images, onImages }, children: _jsx(StateFields, { label: t('@theorem.decision.state'), value: fields, onChange: (next) => {
                         setText(JSON.stringify(next, null, 2));
                     } }) })) : (_jsx(JsonRequest, { label: t('@theorem.decision.state'), text: text, isInvalid: !check.ok, onChange: setText })), withImages && named ? (_jsx(ImageDrop, { onImages: (dropped) => {
                     const next = droppedImages(dropped, { images, host: iface.images, state: named });
                     onImages(next.images);
                     setText(JSON.stringify(next.state, null, 2));
-                } })) : null, _jsx(RunBar, { note: note, isReady: check.ok, isRunning: isRunning, runLabel: t('@theorem.decision.decide'), runningLabel: t('@theorem.decision.deciding'), stopLabel: t('@theorem.decision.stop'), onRun: onRun, onStop: onStop })] }));
+                } })) : null, _jsx(RunBar, { note: note, isReady: isReady, isRunning: isRunning, runLabel: t('@theorem.decision.decide'), runningLabel: t('@theorem.decision.deciding'), stopLabel: t('@theorem.decision.stop'), onRun: onRun, onStop: onStop })] }));
 }
 /** What came back: the failure, the answers, or a spinner until the first of either. */
 function DecisionAnswered({ iface, decision, asked, onQuestion, questionText, }) {
     const t = useLabels();
     const deciding = decision.status === 'deciding';
-    return (_jsxs(_Fragment, { children: [decision.failure ? (_jsx(Banner, { status: "error", role: "alert", title: decision.failure.error })) : null, deciding && !decision.result ? (_jsx(PaneLoading, { label: t('@theorem.decision.deciding'), since: decision.startedAt })) : null, decision.result ? (_jsx(TheoremDecisionAnswers, { iface: iface, result: decision.result, asked: asked, onQuestion: onQuestion, questionText: questionText, elapsedMs: decision.elapsedMs, isStale: deciding })) : null] }));
+    return (_jsxs(_Fragment, { children: [decision.failure ? (_jsx(Banner, { status: "error", role: "alert", title: decision.failure.error })) : null, deciding && !decision.result ? (_jsx(PaneLoading, { label: t('@theorem.decision.deciding'), since: decision.startedAt })) : null, decision.result ? (_jsx(TheoremDecisionAnswers, { iface: decision.result.questions ? { ...iface, questions: decision.result.questions } : iface, result: decision.result, asked: asked, onQuestion: onQuestion, questionText: questionText, elapsedMs: decision.elapsedMs, isStale: deciding })) : null] }));
 }
 /**
  * The frame's second child. A call, not a component: the frame counts its
@@ -91,19 +98,22 @@ function DecisionBody({ transport, iface, decision, defaultState = '{}', default
     const t = useLabels();
     const bytes = useBytes();
     const form = useDecisionState(defaultState, iface.maxStateBytes);
+    const built = useBuildInput(iface.build?.input);
     const { check } = form;
     const [images, setImages] = useState(defaultImages ?? {});
     /** The images and state the answers were asked about, kept with them: later edits don't redraw them. */
     const [asked, setAsked] = useState();
     const inspector = useTraceInspector(iface, transport.traces, trace);
     const decide = () => {
-        if (!check.ok)
+        if (!check.ok || built.missing.length > 0)
             return;
         const sent = namedImages(images, check.state);
         setAsked({ images: { ...iface.images, ...sent }, state: check.state });
-        void decision.decide(check.state, Object.keys(sent).length > 0 ? sent : undefined);
+        void decision.decide(check.state, Object.keys(sent).length > 0 ? sent : undefined, built.schema ? built.input : undefined);
     };
-    return (_jsxs(ConsoleFrame, { inspector: inspector, maxWidth: maxWidth, flush: flush, columns: columns, requestLabel: t('@theorem.decision.state'), className: className, style: style, children: [_jsx(DecisionRequest, { form: form, iface: iface, images: images, onImages: setImages, note: stateNote(t, check, iface.maxStateBytes, bytes), isRunning: decision.status === 'deciding', onRun: decide, onStop: decision.cancel }), decisionResponse(columns, decisionPhase(decision), { answers: t('@theorem.decision.answers'), deciding: t('@theorem.decision.deciding') }, decision.startedAt, _jsx(DecisionAnswered, { iface: iface, decision: decision, asked: asked, onQuestion: onQuestion, questionText: questionText }))] }));
+    return (_jsxs(ConsoleFrame, { inspector: inspector, maxWidth: maxWidth, flush: flush, columns: columns, requestLabel: t('@theorem.decision.state'), className: className, style: style, children: [_jsx(DecisionRequest, { form: form, built: built, iface: iface, images: images, onImages: setImages, note: built.missing.length > 0
+                    ? t('@theorem.host.missing', { fields: built.missing.join(', ') })
+                    : stateNote(t, check, iface.maxStateBytes, bytes), isReady: check.ok && built.missing.length === 0, isRunning: decision.status === 'deciding', onRun: decide, onStop: decision.cancel }), decisionResponse(columns, decisionPhase(decision), { answers: t('@theorem.decision.answers'), deciding: t('@theorem.decision.deciding') }, decision.startedAt, _jsx(DecisionAnswered, { iface: iface, decision: decision, asked: asked, onQuestion: onQuestion, questionText: questionText }))] }));
 }
 function DecisionForTransport(props) {
     const t = useLabels();

package/ui/built/theme.css

@@ -2,8 +2,8 @@
  * @generated by `astryx theme build` — do not edit manually.
  * Source: src/ui/theorem-theme.ts
  * Command: astryx theme build src/ui/theorem-theme.ts --out src/ui/built/theme.css
- * CLI: @astryxdesign/cli@0.7.1
- * Core: @astryxdesign/core@0.7.1
+ * CLI: @astryxdesign/cli@0.7.4
+ * Core: @astryxdesign/core@0.7.4
  */
 
 @layer reset, astryx-base, astryx-theme;

package/ui/built/theme.css.d.ts

@@ -2,8 +2,8 @@
  * @generated by `astryx theme build` — do not edit manually.
  * Source: src/ui/theorem-theme.ts
  * Command: astryx theme build src/ui/theorem-theme.ts --out src/ui/built/theme.css
- * CLI: @astryxdesign/cli@0.7.1
- * Core: @astryxdesign/core@0.7.1
+ * CLI: @astryxdesign/cli@0.7.4
+ * Core: @astryxdesign/core@0.7.4
  */
 
 export {};

package/ui/built/theorem.d.ts

@@ -2,8 +2,8 @@
  * @generated by `astryx theme build` — do not edit manually.
  * Source: src/ui/theorem-theme.ts
  * Command: astryx theme build src/ui/theorem-theme.ts --out src/ui/built/theme.css
- * CLI: @astryxdesign/cli@0.7.1
- * Core: @astryxdesign/core@0.7.1
+ * CLI: @astryxdesign/cli@0.7.4
+ * Core: @astryxdesign/core@0.7.4
  */
 
 /// <reference path="./theorem.variants.d.ts" />

package/ui/built/theorem.js

@@ -2,8 +2,8 @@
  * @generated by `astryx theme build` — do not edit manually.
  * Source: src/ui/theorem-theme.ts
  * Command: astryx theme build src/ui/theorem-theme.ts --out src/ui/built/theme.css
- * CLI: @astryxdesign/cli@0.7.1
- * Core: @astryxdesign/core@0.7.1
+ * CLI: @astryxdesign/cli@0.7.4
+ * Core: @astryxdesign/core@0.7.4
  */
 
 import { neutralTheme } from '@astryxdesign/theme-neutral/built';

package/ui/built/theorem.variants.d.ts

@@ -2,8 +2,8 @@
  * @generated by `astryx theme build` — do not edit manually.
  * Source: src/ui/theorem-theme.ts
  * Command: astryx theme build src/ui/theorem-theme.ts --out src/ui/built/theme.css
- * CLI: @astryxdesign/cli@0.7.1
- * Core: @astryxdesign/core@0.7.1
+ * CLI: @astryxdesign/cli@0.7.4
+ * Core: @astryxdesign/core@0.7.4
  */
 
 // Generated by astryx theme build