vultus-core 0.1.1 → 0.2.0

package/dist/useActionList.js

@@ -6,9 +6,9 @@ import { resolveActionFields, makeFirePromise, assembleStatus } from './action-c
 /**
  * Build a DYNAMIC list of actions from a spec array — the list counterpart to
  * useAction. The hook count is fixed regardless of list length (one shared
- * error context, one pending/errors map, one memo), so it is usable where
+ * error context, one pending/messages map, one memo), so it is usable where
  * useAction — a per-call hook — cannot be looped (rules of hooks). Pending and
- * errors are tracked per action id in the shared maps; each action gets real
+ * messages are tracked per action id in the shared maps; each action gets real
  * per-item pending. The firing machinery + ActionStatus shape are the exact
  * same shared helpers useAction uses (see action-core.ts) — nothing is
  * reimplemented.
@@ -20,7 +20,7 @@ export function useActionList(specs, registry) {
     const { t } = useTranslation();
     const messageSink = useMessageSink();
     const [pendingMap, setPendingMap] = useState({});
-    const [errorsMap, setErrorsMap] = useState({});
+    const [messagesMap, setMessagesMap] = useState({});
     const pendingRef = useRef(pendingMap);
     pendingRef.current = pendingMap;
     return useMemo(() => specs.map((opts) => {
@@ -30,13 +30,13 @@ export function useActionList(specs, registry) {
             reason: fields.reason,
             getPending: () => !!pendingRef.current[opts.id],
             setPending: (value) => setPendingMap((m) => ({ ...m, [opts.id]: value })),
-            setErrors: (errs) => setErrorsMap((m) => ({ ...m, [opts.id]: errs })),
+            setMessages: (msgs) => setMessagesMap((m) => ({ ...m, [opts.id]: msgs })),
             errCtxRef,
             t,
             registry,
             messageSink,
         });
-        return assembleStatus(opts, fields, !!pendingMap[opts.id], errorsMap[opts.id] ?? [], firePromise);
-    }), [specs, pendingMap, errorsMap, registry, t, messageSink]);
+        return assembleStatus(opts, fields, !!pendingMap[opts.id], messagesMap[opts.id] ?? [], firePromise);
+    }), [specs, pendingMap, messagesMap, registry, t, messageSink]);
 }
 //# sourceMappingURL=useActionList.js.map

package/dist/useActionList.js.map

@@ -1 +1 @@
-{"version":3,"file":"useActionList.js","sourceRoot":"","sources":["../src/useActionList.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGxF;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,KAA+C,EAC/C,QAAuC;IAEvC,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;IAC3B,MAAM,EAAE,CAAC,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IAErC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAA0B,EAAE,CAAC,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAA2B,EAAE,CAAC,CAAC;IACzE,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACtC,UAAU,CAAC,OAAO,GAAG,UAAU,CAAC;IAEhC,OAAO,OAAO,CACZ,GAAG,EAAE,CACH,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,EAAE;YACxC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/C,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YACzE,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,SAAS;YACT,CAAC;YACD,QAAQ;YACR,WAAW;SACZ,CAAC,CAAC;QACH,OAAO,cAAc,CACnB,IAAI,EACJ,MAAM,EACN,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,EACrB,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,EACxB,WAAW,CACZ,CAAC;IACJ,CAAC,CAAC,EACJ,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,CAAC,CACzD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"useActionList.js","sourceRoot":"","sources":["../src/useActionList.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGxF;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,KAA+C,EAC/C,QAAuC;IAEvC,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;IAC3B,MAAM,EAAE,CAAC,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IAErC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAA0B,EAAE,CAAC,CAAC;IAC1E,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAA4B,EAAE,CAAC,CAAC;IAC9E,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACtC,UAAU,CAAC,OAAO,GAAG,UAAU,CAAC;IAEhC,OAAO,OAAO,CACZ,GAAG,EAAE,CACH,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,EAAE;YACxC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/C,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YACzE,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YACzE,SAAS;YACT,CAAC;YACD,QAAQ;YACR,WAAW;SACZ,CAAC,CAAC;QACH,OAAO,cAAc,CACnB,IAAI,EACJ,MAAM,EACN,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,EACrB,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,EAC1B,WAAW,CACZ,CAAC;IACJ,CAAC,CAAC,EACJ,CAAC,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,CAAC,CAC3D,CAAC;AACJ,CAAC"}

package/dist/useBoolField.d.ts

@@ -0,0 +1,17 @@
+import { type FieldControls, type FieldOptions } from './field.js';
+import type { ErrorRoutesRegistry } from './types.js';
+export type BoolFieldOptions<RouteId extends string = string> = FieldOptions<boolean, boolean, RouteId>;
+export interface BoolFieldControls extends FieldControls<boolean, boolean> {
+    /**
+     * Request the opposite value. Programmatic use; widgets obtain the field's
+     * confirmation for `!value` first, then call `setValue`.
+     */
+    toggle(): void;
+}
+/**
+ * A boolean field (moxb's Bool, the sidedao boolean field). Rendered by
+ * vultus-antd's BoolCheckbox and BoolSwitch, which take the same controls.
+ * Inside the field the value starts at `initialValue` (default false).
+ */
+export declare function useBoolField<RouteId extends string = string>(opts: BoolFieldOptions<RouteId>, registry?: ErrorRoutesRegistry<RouteId>): BoolFieldControls;
+//# sourceMappingURL=useBoolField.d.ts.map

package/dist/useBoolField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBoolField.d.ts","sourceRoot":"","sources":["../src/useBoolField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,gBAAgB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAExG,MAAM,WAAW,iBAAkB,SAAQ,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC;IACxE;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,EAC1D,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAC/B,QAAQ,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,GACtC,iBAAiB,CAQnB"}

package/dist/useBoolField.js

@@ -0,0 +1,12 @@
+import { useFieldCore } from './field.js';
+/**
+ * A boolean field (moxb's Bool, the sidedao boolean field). Rendered by
+ * vultus-antd's BoolCheckbox and BoolSwitch, which take the same controls.
+ * Inside the field the value starts at `initialValue` (default false).
+ */
+export function useBoolField(opts, registry) {
+    const inside = !opts.onChange && !opts.commit;
+    const field = useFieldCore('boolean', inside ? { ...opts, initialValue: opts.initialValue ?? false } : opts, registry);
+    return { ...field, toggle: () => field.setValue(!field.value) };
+}
+//# sourceMappingURL=useBoolField.js.map

package/dist/useBoolField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBoolField.js","sourceRoot":"","sources":["../src/useBoolField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyC,MAAM,YAAY,CAAC;AAajF;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,IAA+B,EAC/B,QAAuC;IAEvC,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC9C,MAAM,KAAK,GAAG,YAAY,CACxB,SAAS,EACT,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,EACrE,QAAQ,CACT,CAAC;IACF,OAAO,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;AAClE,CAAC"}

package/dist/useMixedBoolField.d.ts

@@ -0,0 +1,24 @@
+import { type FieldControls, type FieldOptions } from './field.js';
+import type { ErrorRoutesRegistry } from './types.js';
+/** What a mixed boolean field shows: on, off, or some of its items on and some off. */
+export type MixedBool = boolean | 'mixed';
+export type MixedBoolFieldOptions<RouteId extends string = string> = FieldOptions<MixedBool, boolean, RouteId>;
+export interface MixedBoolFieldControls extends FieldControls<MixedBool, boolean> {
+    /** Request the opposite: off when on, on when off or mixed. Programmatic use, as in BoolFieldControls. */
+    toggle(): void;
+}
+/**
+ * A boolean field over an aggregate (moxb's indeterminate Bool, ARIA's
+ * "mixed"): it shows true, false or 'mixed', and can be asked for true or
+ * false only. Rendered by the same widgets as useBoolField: BoolSwitch puts
+ * its knob in the middle, BoolCheckbox is indeterminate. Derive the value with
+ * `aggregateBool`; with no items at all, disable the field with a reason.
+ */
+export declare function useMixedBoolField<RouteId extends string = string>(opts: MixedBoolFieldOptions<RouteId>, registry?: ErrorRoutesRegistry<RouteId>): MixedBoolFieldControls;
+/**
+ * The aggregate of several booleans: true when all are on, false when none is,
+ * 'mixed' otherwise; `undefined` when there are none (a case for disabling the
+ * field, not a value).
+ */
+export declare function aggregateBool(values: readonly boolean[]): MixedBool | undefined;
+//# sourceMappingURL=useMixedBoolField.d.ts.map

package/dist/useMixedBoolField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMixedBoolField.d.ts","sourceRoot":"","sources":["../src/useMixedBoolField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,uFAAuF;AACvF,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1C,MAAM,MAAM,qBAAqB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,YAAY,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAE/G,MAAM,WAAW,sBAAuB,SAAQ,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC;IAC/E,0GAA0G;IAC1G,MAAM,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/D,IAAI,EAAE,qBAAqB,CAAC,OAAO,CAAC,EACpC,QAAQ,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,GACtC,sBAAsB,CAQxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GAAG,SAAS,CAI/E"}

package/dist/useMixedBoolField.js

@@ -0,0 +1,25 @@
+import { useFieldCore } from './field.js';
+/**
+ * A boolean field over an aggregate (moxb's indeterminate Bool, ARIA's
+ * "mixed"): it shows true, false or 'mixed', and can be asked for true or
+ * false only. Rendered by the same widgets as useBoolField: BoolSwitch puts
+ * its knob in the middle, BoolCheckbox is indeterminate. Derive the value with
+ * `aggregateBool`; with no items at all, disable the field with a reason.
+ */
+export function useMixedBoolField(opts, registry) {
+    const inside = !opts.onChange && !opts.commit;
+    const field = useFieldCore('mixed-boolean', inside ? { ...opts, initialValue: opts.initialValue ?? false } : opts, registry);
+    return { ...field, toggle: () => field.setValue(field.value !== true) };
+}
+/**
+ * The aggregate of several booleans: true when all are on, false when none is,
+ * 'mixed' otherwise; `undefined` when there are none (a case for disabling the
+ * field, not a value).
+ */
+export function aggregateBool(values) {
+    if (values.length === 0)
+        return undefined;
+    const on = values.filter(Boolean).length;
+    return on === values.length ? true : on === 0 ? false : 'mixed';
+}
+//# sourceMappingURL=useMixedBoolField.js.map

package/dist/useMixedBoolField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMixedBoolField.js","sourceRoot":"","sources":["../src/useMixedBoolField.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyC,MAAM,YAAY,CAAC;AAajF;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAoC,EACpC,QAAuC;IAEvC,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC9C,MAAM,KAAK,GAAG,YAAY,CACxB,eAAe,EACf,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,EACrE,QAAQ,CACT,CAAC;IACF,OAAO,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAA0B;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACzC,OAAO,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;AAClE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vultus-core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "Apache-2.0",
   "description": "Framework-neutral action model + hooks for vultus (antd-free by design)",
   "repository": {

package/src/MessageSink.tsx

@@ -1,12 +1,15 @@
 import { createContext, useContext } from 'react';
+import type { Severity } from './types.js';
 
 /**
- * How the action framework surfaces an otherwise-unhandled error (no form field,
- * no inline error target). Default is a no-op so vultus-core stays antd-free and
- * framework-neutral; vultus-antd's VultusProvider wires this to antd's
- * message.error. Hosts may inject any toast/notification mechanism.
+ * How the action framework surfaces messages: an otherwise-unhandled error (no
+ * form field, no inline error target), and the messages an action reports
+ * through its ExecutionContext. `severity` defaults to 'error'. Default is a
+ * no-op so vultus-core stays antd-free and framework-neutral; vultus-antd's
+ * VultusProvider wires this to antd's message API. Hosts may inject any
+ * toast/notification mechanism.
  */
-export type MessageSink = (text: string) => void;
+export type MessageSink = (text: string, severity?: Severity) => void;
 
 export const MessageSinkContext = createContext<MessageSink>(() => {});
 

package/src/action-core.ts

@@ -12,6 +12,9 @@ import type {
   ConfirmationSpec,
   Decision,
   ErrorRoutesRegistry,
+  ExecutionContext,
+  Message,
+  Severity,
 } from './types.js';
 
 /**
@@ -49,7 +52,7 @@ export interface FirePromiseDeps<RouteId extends string> {
   reason: string | undefined;
   getPending: () => boolean;
   setPending: (value: boolean) => void;
-  setErrors: (errors: string[]) => void;
+  setMessages: (messages: Message[]) => void;
   errCtxRef: MutableRefObject<ActionErrorCtx | null>;
   t: (key: string, opts?: Record<string, unknown>) => string;
   registry?: ErrorRoutesRegistry<RouteId>;
@@ -70,13 +73,26 @@ export function makeFirePromise<TArgs, TResult, RouteId extends string>(
       console.warn(`Action '${opts.id}': already pending — ignoring fire`);
       return;
     }
-    deps.setErrors([]);
+    // Messages of this run: reported through the context while it runs, then
+    // the thrown error if it fails. Each report updates the status at once.
+    const messages: Message[] = [];
+    const report = (severity: Severity) => (text: string) => {
+      messages.push({ text, severity });
+      deps.setMessages([...messages]);
+      deps.messageSink?.(text, severity);
+    };
+    const ctx: ExecutionContext = { info: report('info'), warn: report('warning'), error: report('error') };
+    deps.setMessages([]);
     deps.setPending(true);
     try {
-      const result = await opts.fire(args);
+      const result = await opts.fire(args, ctx);
       opts.onSuccess?.(result as TResult);
     } catch (err) {
+      const parsed = parseApiError(err);
+      const text = parsed.message ?? 'Action failed';
       if (opts.errorRoute && deps.registry) {
+        // A routed action: routeApiError decides where the error shows (a form
+        // field, the inline error, or the sink).
         routeApiError(
           err,
           {
@@ -88,9 +104,12 @@ export function makeFirePromise<TArgs, TResult, RouteId extends string>(
           },
           deps.registry,
         );
+      } else {
+        // No route: the sink shows it, like the messages reported through ctx.
+        deps.messageSink?.(text, 'error');
       }
-      const parsed = parseApiError(err);
-      deps.setErrors([parsed.message ?? 'Action failed']);
+      messages.push({ text, severity: 'error' });
+      deps.setMessages([...messages]);
     } finally {
       deps.setPending(false);
     }
@@ -102,7 +121,7 @@ export function assembleStatus<TArgs>(
   opts: ActionOptions<TArgs, any, any>,
   fields: ResolvedFields,
   pending: boolean,
-  errors: string[],
+  messages: Message[],
   firePromise: (args: TArgs) => Promise<void>,
 ): ActionStatus<TArgs> {
   const fire = (args: TArgs) => {
@@ -118,7 +137,8 @@ export function assembleStatus<TArgs>(
     reason: fields.reason,
     invisible: fields.invisible,
     confirmation: fields.confirmation,
-    errors,
+    messages,
+    errors: messages.filter((m) => m.severity === 'error').map((m) => m.text),
     fire: fire as ActionStatus<TArgs>['fire'],
     firePromise: firePromise as ActionStatus<TArgs>['firePromise'],
   };

package/src/decision.ts

@@ -19,3 +19,7 @@ export const andDecisions = (a: Decision, b: Decision): Decision => {
   }
   return av ? b : a;
 };
+
+/** The opposite verdict, keeping the reason (a reason to disable is a reason not to enable). */
+export const invertDecision = (d: Decision): Decision =>
+  typeof d === 'boolean' ? !d : { verdict: !d.verdict, reason: d.reason };

package/src/field.ts

@@ -0,0 +1,197 @@
+import { useState } from 'react';
+import { getReason, getVerdict, invertDecision } from './decision.js';
+import { resolve } from './resolve.js';
+import { useAction } from './useAction.js';
+import type {
+  ConfirmationSpec,
+  Decision,
+  ErrorRoutesRegistry,
+  ExecutionContext,
+  Message,
+  ValueOrFn,
+} from './types.js';
+
+/**
+ * Fields: the value half of vultus, on the pattern of the sidedao InputFields.
+ * A field hook (useBoolField, later others) is built on useFieldCore by
+ * composition, never by inheritance. A field's value lives either inside the
+ * field (its own state) or outside it (the caller passes it every render);
+ * from outside it is changed either locally (`onChange`, e.g. a form) or by an
+ * immediate commit (`commit`), whose setter runs as an action.
+ * Design notes: unitas docs/2026-10-05-vultus-field-model-design.md.
+ */
+
+/** How an immediately committing field stores a change: an action that receives the requested value. */
+export interface FieldCommit<TRequest, RouteId extends string = string> {
+  fire: (next: TRequest, ctx: ExecutionContext) => Promise<void> | void;
+  /** Confirmation before committing; may depend on the requested value (e.g. only when switching off). */
+  confirmation?: ConfirmationSpec | ((next: TRequest) => ConfirmationSpec | undefined);
+  errorRoute?: RouteId;
+}
+
+/** The key of a value in `valueDescriptions`: 'true' / 'false' for booleans, the value itself for strings. */
+export type ValueKey<T> = T extends boolean ? `${T}` : T extends string | number ? `${T}` : never;
+
+interface FieldBaseOptions<TValue> {
+  id: string;
+  label?: ValueOrFn<string>;
+  description?: ValueOrFn<string | undefined>;
+  /** Shown? Default true. Use `visible` or `hidden`, not contradicting each other. */
+  visible?: ValueOrFn<boolean>;
+  hidden?: ValueOrFn<boolean>;
+  /** Changeable? Default true, optionally with a reason. Use `enabled` or `disabled`, not contradicting each other. */
+  enabled?: ValueOrFn<Decision>;
+  disabled?: ValueOrFn<Decision>;
+  /**
+   * What each value means right now, keyed by value (for booleans `true` / `false`, and `mixed`
+   * where the field can show it). Shown with the current value, next to `description`, which
+   * says what the field is in general.
+   */
+  valueDescriptions?: Partial<Record<ValueKey<TValue>, string>>;
+}
+
+/**
+ * Where the value lives, and what setting it does. Exactly one of the three. The field shows a
+ * `TValue` and can be asked for a `TRequest`; usually the same type, but an aggregate can show
+ * a state that cannot be requested (a boolean field showing 'mixed').
+ */
+export type FieldStorage<TValue, TRequest = TValue, RouteId extends string = string> =
+  /** Inside the field: its own state, starting at `initialValue`. */
+  | { initialValue?: TValue; value?: never; onChange?: never; commit?: never }
+  /** Outside, changed locally: the caller owns the value and applies `onChange`. */
+  | { value: TValue; onChange: (value: TRequest) => void; initialValue?: never; commit?: never }
+  /** Outside, committed immediately: `commit.fire` stores the change (pending, messages, confirmation). */
+  | { value: TValue; commit: FieldCommit<TRequest, RouteId>; initialValue?: never; onChange?: never };
+
+export type FieldOptions<TValue, TRequest = TValue, RouteId extends string = string> =
+  FieldBaseOptions<TValue> & FieldStorage<TValue, TRequest, RouteId>;
+
+/** What a field widget receives: everything it shows, and the one way to change the value. */
+export interface FieldControls<TValue, TRequest = TValue> {
+  type: string;
+  id: string;
+  label: string;
+  description: string | undefined;
+  /** What the current value means (from `valueDescriptions`). */
+  valueDescription: string | undefined;
+  visible: boolean;
+  enabled: boolean;
+  whyDisabled: string | undefined;
+  value: TValue;
+  /** Request a new value. Ignored (with a warning) when disabled or while a commit is pending. */
+  setValue(next: TRequest): void;
+  /** A commit is running. */
+  pending: boolean;
+  /** Messages of the last commit. */
+  messages: Message[];
+  /** The confirmation a widget must obtain before requesting `next`, if any. */
+  confirmationFor(next: TRequest): ConfirmationSpec | undefined;
+}
+
+export type FieldStorageMode = 'inside' | 'local' | 'commit';
+
+export function fieldStorageMode(id: string, opts: FieldStorage<unknown, unknown, string>): FieldStorageMode {
+  const { initialValue, value, onChange, commit } = opts as {
+    initialValue?: unknown; value?: unknown; onChange?: unknown; commit?: unknown;
+  };
+  if (commit && onChange) throw new Error(`Field '${id}': "commit" and "onChange" are mutually exclusive`);
+  if ((commit || onChange) && initialValue !== undefined) {
+    throw new Error(`Field '${id}': "initialValue" is for a value inside the field; with "${commit ? 'commit' : 'onChange'}" the caller passes "value"`);
+  }
+  if (commit) return 'commit';
+  if (onChange) return 'local';
+  if (value !== undefined) throw new Error(`Field '${id}': "value" needs "onChange" or "commit"`);
+  return 'inside';
+}
+
+export function calculateVisible(id: string, visible: boolean | undefined, hidden: boolean | undefined): boolean {
+  if (visible === undefined) return hidden === undefined ? true : !hidden;
+  if (hidden === undefined || visible !== hidden) return visible;
+  throw new Error(`Field '${id}': "visible" and "hidden" contradict each other`);
+}
+
+export function calculateEnabled(id: string, enabled: Decision | undefined, disabled: Decision | undefined): Decision {
+  if (enabled === undefined) return disabled === undefined ? true : invertDecision(disabled);
+  if (disabled === undefined) return enabled;
+  if (getVerdict(enabled, false) !== getVerdict(disabled, false)) {
+    return { verdict: getVerdict(enabled, false), reason: getReason(disabled) ?? getReason(enabled) };
+  }
+  throw new Error(`Field '${id}': "enabled" and "disabled" contradict each other`);
+}
+
+/**
+ * The shared core of every field hook: label and description, visibility and
+ * enabled state (with reason), the storage mode, and in commit mode the setter
+ * as an action (its pending state and messages become the field's).
+ */
+export function useFieldCore<TValue, TRequest extends TValue = TValue, RouteId extends string = string>(
+  type: string,
+  opts: FieldOptions<TValue, TRequest, RouteId>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): FieldControls<TValue, TRequest> {
+  const mode = fieldStorageMode(opts.id, opts as FieldStorage<unknown, unknown, string>);
+  const [inner, setInner] = useState<TValue>(opts.initialValue as TValue);
+
+  const label = resolve(opts.label, '');
+  const description = resolve<string | undefined>(opts.description, undefined);
+  const visible = calculateVisible(
+    opts.id,
+    resolve<boolean | undefined>(opts.visible, undefined),
+    resolve<boolean | undefined>(opts.hidden, undefined),
+  );
+  const enabledDecision = calculateEnabled(
+    opts.id,
+    resolve<Decision | undefined>(opts.enabled, undefined),
+    resolve<Decision | undefined>(opts.disabled, undefined),
+  );
+  const enabled = getVerdict(enabledDecision, true);
+  const whyDisabled = enabled ? undefined : getReason(enabledDecision);
+
+  // Hooks run unconditionally; the setter action is only fired in commit mode.
+  const setter = useAction<TRequest, void, RouteId>(
+    {
+      id: `${opts.id}.set`,
+      label,
+      enabled: enabledDecision,
+      invisible: !visible,
+      errorRoute: opts.commit?.errorRoute,
+      fire: (next, ctx) => opts.commit?.fire(next, ctx),
+    },
+    registry,
+  );
+
+  const value = mode === 'inside' ? inner : (opts.value as TValue);
+  const pending = mode === 'commit' && setter.pending;
+  const valueDescription = (opts.valueDescriptions as Record<string, string | undefined> | undefined)?.[String(value)];
+
+  const setValue = (next: TRequest) => {
+    if (!enabled) {
+      console.warn(`Field '${opts.id}': disabled — ${whyDisabled ?? '(no reason)'}`);
+      return;
+    }
+    if (mode === 'inside') setInner(next);
+    else if (mode === 'local') opts.onChange!(next);
+    else (setter.fire as (args: TRequest) => void)(next);
+  };
+
+  const confirmationFor = (next: TRequest): ConfirmationSpec | undefined => {
+    const spec = opts.commit?.confirmation;
+    return typeof spec === 'function' ? spec(next) : spec;
+  };
+
+  return {
+    type,
+    id: opts.id,
+    label,
+    description,
+    valueDescription,
+    visible,
+    enabled,
+    whyDisabled,
+    value,
+    setValue,
+    pending,
+    messages: mode === 'commit' ? (setter.messages ?? []) : [],
+    confirmationFor,
+  };
+}

package/src/index.ts

@@ -6,5 +6,13 @@ export * from './routeApiError.js';
 export { ActionErrorContext, useActionErrorCtx } from './useActionErrorCtx.js';
 export { useAction } from './useAction.js';
 export { useActionList } from './useActionList.js';
+export {
+  useFieldCore, fieldStorageMode, calculateVisible, calculateEnabled,
+  type FieldCommit, type FieldControls, type FieldOptions, type FieldStorage, type FieldStorageMode, type ValueKey,
+} from './field.js';
+export { useBoolField, type BoolFieldControls, type BoolFieldOptions } from './useBoolField.js';
+export {
+  useMixedBoolField, aggregateBool, type MixedBool, type MixedBoolFieldControls, type MixedBoolFieldOptions,
+} from './useMixedBoolField.js';
 export { InternalLinkContext, useInternalLink, type InternalLinkComponent } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink, type MessageSink } from './MessageSink.js';

package/src/types.ts

@@ -12,6 +12,26 @@ export interface FormLike {
 export type Decision = boolean | { verdict: boolean; reason?: string };
 export type ValueOrFn<T> = T | (() => T);
 
+export type Severity = 'info' | 'warning' | 'error';
+
+/** Something an action (or, later, a field's validation) has to say, with its severity. */
+export interface Message {
+  text: string;
+  severity: Severity;
+}
+
+/**
+ * What an action's `fire` receives next to its arguments: a way to report
+ * messages while it runs (absorbed from the sidedao InputFields). Messages land
+ * on the action's status (`messages`) and go to the MessageSink. A thrown
+ * error still fails the action; `error()` reports an error without throwing.
+ */
+export interface ExecutionContext {
+  info(text: string): void;
+  warn(text: string): void;
+  error(text: string): void;
+}
+
 export type ConfirmationSpec =
   | { kind: 'popconfirm'; question: string }
   | { kind: 'cascade-modal'; title: string; content: React.ReactNode }
@@ -26,7 +46,7 @@ export interface ActionOptions<TArgs = void, TResult = void, RouteId extends str
   invisible?: ValueOrFn<boolean>;
   confirmation?: ValueOrFn<ConfirmationSpec | undefined>;
   errorRoute?: RouteId;
-  fire: (args: TArgs) => Promise<TResult> | TResult;
+  fire: (args: TArgs, ctx: ExecutionContext) => Promise<TResult> | TResult;
   onSuccess?: (result: TResult) => void;
 }
 
@@ -45,6 +65,13 @@ export interface ActionStatus<TArgs = void> {
   reason?: string;
   invisible: boolean;
   confirmation?: ConfirmationSpec;
+  /**
+   * Messages of the last run: reported through the ExecutionContext, or the thrown error.
+   * Optional so hand-built statuses (adapters, test fixtures) stay valid; read it as `[]` when
+   * absent. Statuses from useAction and useActionList always carry it.
+   */
+  messages?: Message[];
+  /** The error texts among `messages` (kept for callers that only show errors). */
   errors: string[];
   fire(...args: FireArgs<TArgs>): void;
   firePromise(...args: FireArgs<TArgs>): Promise<void>;

package/src/useAction.ts

@@ -3,7 +3,7 @@ import { useTranslation } from 'react-i18next';
 import { useActionErrorCtx } from './useActionErrorCtx.js';
 import { useMessageSink } from './MessageSink.js';
 import { resolveActionFields, makeFirePromise, assembleStatus } from './action-core.js';
-import type { ActionOptions, ActionStatus, ErrorRoutesRegistry } from './types.js';
+import type { ActionOptions, ActionStatus, ErrorRoutesRegistry, Message } from './types.js';
 
 export function useAction<TArgs = void, TResult = void, RouteId extends string = string>(
   opts: ActionOptions<TArgs, TResult, RouteId>,
@@ -16,7 +16,7 @@ export function useAction<TArgs = void, TResult = void, RouteId extends string =
   const messageSink = useMessageSink();
 
   const [pending, setPending] = useState(false);
-  const [errors, setErrors] = useState<string[]>([]);
+  const [messages, setMessages] = useState<Message[]>([]);
   const pendingRef = useRef(pending);
   pendingRef.current = pending;
 
@@ -29,7 +29,7 @@ export function useAction<TArgs = void, TResult = void, RouteId extends string =
         reason: fields.reason,
         getPending: () => pendingRef.current,
         setPending,
-        setErrors,
+        setMessages,
         errCtxRef,
         t,
         registry,
@@ -42,7 +42,7 @@ export function useAction<TArgs = void, TResult = void, RouteId extends string =
   // primitives below, not on the whole `opts`/`fields` objects (which are
   // fresh each render and would defeat the memo).
   return useMemo<ActionStatus<TArgs>>(
-    () => assembleStatus(opts, fields, pending, errors, firePromise),
+    () => assembleStatus(opts, fields, pending, messages, firePromise),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
       opts.id,
@@ -54,7 +54,7 @@ export function useAction<TArgs = void, TResult = void, RouteId extends string =
       fields.reason,
       fields.invisible,
       fields.confirmation,
-      errors,
+      messages,
       firePromise,
     ],
   );

package/src/useActionList.ts

@@ -3,14 +3,14 @@ import { useTranslation } from 'react-i18next';
 import { useActionErrorCtx } from './useActionErrorCtx.js';
 import { useMessageSink } from './MessageSink.js';
 import { resolveActionFields, makeFirePromise, assembleStatus } from './action-core.js';
-import type { ActionOptions, ActionStatus, ErrorRoutesRegistry } from './types.js';
+import type { ActionOptions, ActionStatus, ErrorRoutesRegistry, Message } from './types.js';
 
 /**
  * Build a DYNAMIC list of actions from a spec array — the list counterpart to
  * useAction. The hook count is fixed regardless of list length (one shared
- * error context, one pending/errors map, one memo), so it is usable where
+ * error context, one pending/messages map, one memo), so it is usable where
  * useAction — a per-call hook — cannot be looped (rules of hooks). Pending and
- * errors are tracked per action id in the shared maps; each action gets real
+ * messages are tracked per action id in the shared maps; each action gets real
  * per-item pending. The firing machinery + ActionStatus shape are the exact
  * same shared helpers useAction uses (see action-core.ts) — nothing is
  * reimplemented.
@@ -26,7 +26,7 @@ export function useActionList<TArgs = void, TResult = void, RouteId extends stri
   const messageSink = useMessageSink();
 
   const [pendingMap, setPendingMap] = useState<Record<string, boolean>>({});
-  const [errorsMap, setErrorsMap] = useState<Record<string, string[]>>({});
+  const [messagesMap, setMessagesMap] = useState<Record<string, Message[]>>({});
   const pendingRef = useRef(pendingMap);
   pendingRef.current = pendingMap;
 
@@ -39,7 +39,7 @@ export function useActionList<TArgs = void, TResult = void, RouteId extends stri
           reason: fields.reason,
           getPending: () => !!pendingRef.current[opts.id],
           setPending: (value) => setPendingMap((m) => ({ ...m, [opts.id]: value })),
-          setErrors: (errs) => setErrorsMap((m) => ({ ...m, [opts.id]: errs })),
+          setMessages: (msgs) => setMessagesMap((m) => ({ ...m, [opts.id]: msgs })),
           errCtxRef,
           t,
           registry,
@@ -49,10 +49,10 @@ export function useActionList<TArgs = void, TResult = void, RouteId extends stri
           opts,
           fields,
           !!pendingMap[opts.id],
-          errorsMap[opts.id] ?? [],
+          messagesMap[opts.id] ?? [],
           firePromise,
         );
       }),
-    [specs, pendingMap, errorsMap, registry, t, messageSink],
+    [specs, pendingMap, messagesMap, registry, t, messageSink],
   );
 }