vultus-core 0.1.0 → 0.2.0

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],
   );
 }

package/src/useBoolField.ts

@@ -0,0 +1,30 @@
+import { useFieldCore, 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 function useBoolField<RouteId extends string = string>(
+  opts: BoolFieldOptions<RouteId>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): BoolFieldControls {
+  const inside = !opts.onChange && !opts.commit;
+  const field = useFieldCore<boolean, boolean, RouteId>(
+    'boolean',
+    inside ? { ...opts, initialValue: opts.initialValue ?? false } : opts,
+    registry,
+  );
+  return { ...field, toggle: () => field.setValue(!field.value) };
+}

package/src/useMixedBoolField.ts

@@ -0,0 +1,43 @@
+import { useFieldCore, 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 function useMixedBoolField<RouteId extends string = string>(
+  opts: MixedBoolFieldOptions<RouteId>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): MixedBoolFieldControls {
+  const inside = !opts.onChange && !opts.commit;
+  const field = useFieldCore<MixedBool, boolean, RouteId>(
+    '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: readonly boolean[]): MixedBool | undefined {
+  if (values.length === 0) return undefined;
+  const on = values.filter(Boolean).length;
+  return on === values.length ? true : on === 0 ? false : 'mixed';
+}