vultus-core 0.1.1 → 0.2.1

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';
+}