vultus-core 0.2.1 → 0.3.0

package/README.md

@@ -61,6 +61,16 @@ and can be asked for `true` or `false` only (the field core separates the shown
 requestable one); a toggle from mixed requests `true`. `aggregateBool(values)` derives the
 value; with no items at all, disable the field with a reason instead.
 
+`useOneOfField` is a field whose value is one of a list of `choices` (static or derived):
+each `{ value, label?, description?, icon?, enabled?/disabled?, variant? }`. A choice may
+be disabled with a reason (a `Decision`, as a field's), and be `primary` or `danger` like an
+action's variant; `description` (markdown) says what choosing it does and is also the field's
+current state while it is chosen, unless `valueDescriptions` words that state differently.
+Requesting a disabled or unknown choice is ignored with a warning. Storage is as for the
+boolean field (inside: `initialValue`, default the first enabled choice); `confirmation` may
+depend on the requested choice. vultus-antd's `OneOfSelect` and `OneOfSegmented` take the
+same field.
+
 ## Distribution
 
 This package ships compiled ESM (`dist/`) with TypeScript declarations to

package/dist/index.d.ts

@@ -9,6 +9,7 @@ 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 { useOneOfField, type OneOfChoice, type OneOfChoiceControls, type OneOfFieldControls, type OneOfFieldOptions, } from './useOneOfField.js';
 export { InternalLinkContext, useInternalLink, type InternalLinkComponent } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink, type MessageSink } from './MessageSink.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAClE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,KAAK,QAAQ,GACjH,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,GAC1G,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAClE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,KAAK,QAAQ,GACjH,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,GAC1G,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,GAC3G,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -9,6 +9,7 @@ export { useActionList } from './useActionList.js';
 export { useFieldCore, fieldStorageMode, calculateVisible, calculateEnabled, } from './field.js';
 export { useBoolField } from './useBoolField.js';
 export { useMixedBoolField, aggregateBool, } from './useMixedBoolField.js';
+export { useOneOfField, } from './useOneOfField.js';
 export { InternalLinkContext, useInternalLink } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink } from './MessageSink.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,GAEnE,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAiD,MAAM,mBAAmB,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,aAAa,GACjC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAA8B,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,GAEnE,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAiD,MAAM,mBAAmB,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,aAAa,GACjC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAA8B,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,kBAAkB,CAAC"}

package/dist/useOneOfField.d.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+import { type FieldControls, type FieldOptions } from './field.js';
+import type { Decision, ErrorRoutesRegistry, ValueOrFn } from './types.js';
+/** One choice of a one-of field (moxb's BindOneOfChoice). */
+export interface OneOfChoice<T extends string = string> {
+    value: T;
+    /** Shown for the choice; default: the value. */
+    label?: string;
+    /** What choosing it does (moxb's `help`), markdown; also the field's current state when it is chosen. */
+    description?: string;
+    /** Shown before the label (or instead of it, for an icon-only widget), like an action's icon. */
+    icon?: ReactNode;
+    /** Choosable? Default true, optionally with a reason. Use `enabled` or `disabled`, not contradicting each other. */
+    enabled?: Decision;
+    disabled?: Decision;
+    /** Shown as the main or a dangerous choice, like an action's variant. Default 'default'. */
+    variant?: 'default' | 'primary' | 'danger';
+    /** A heading the choice is listed under, after the choices without one (OneOfSelect); default none. */
+    group?: string;
+}
+/** A choice as the widgets get it. */
+export interface OneOfChoiceControls<T extends string = string> {
+    value: T;
+    label: string;
+    description: string | undefined;
+    icon: ReactNode | undefined;
+    enabled: boolean;
+    whyDisabled: string | undefined;
+    variant: 'default' | 'primary' | 'danger';
+    group: string | undefined;
+}
+export type OneOfFieldOptions<T extends string = string, RouteId extends string = string> = FieldOptions<T, T, RouteId> & {
+    /** The choices, in order; static or derived. */
+    choices: ValueOrFn<OneOfChoice<T>[]>;
+};
+export interface OneOfFieldControls<T extends string = string> extends FieldControls<T, T> {
+    choices: OneOfChoiceControls<T>[];
+    /** The choice the value is, if it is one of them. */
+    current: OneOfChoiceControls<T> | undefined;
+}
+/**
+ * A field whose value is one of a list of choices (moxb's OneOf). Rendered by
+ * vultus-antd's OneOfSelect and OneOfSegmented, which take the same controls.
+ * Each choice may be disabled with a reason; the field's current state is the
+ * current choice's description unless `valueDescriptions` words it
+ * differently. Requesting a disabled or unknown choice is ignored with a
+ * warning, as a disabled field ignores any request. Inside the field the value
+ * starts at `initialValue`, else at the first enabled choice.
+ */
+export declare function useOneOfField<T extends string = string, RouteId extends string = string>(opts: OneOfFieldOptions<T, RouteId>, registry?: ErrorRoutesRegistry<RouteId>): OneOfFieldControls<T>;
+//# sourceMappingURL=useOneOfField.d.ts.map

package/dist/useOneOfField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOneOfField.d.ts","sourceRoot":"","sources":["../src/useOneOfField.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAkC,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAGnG,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3E,6DAA6D;AAC7D,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACpD,KAAK,EAAE,CAAC,CAAC;IACT,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yGAAyG;IACzG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,oHAAoH;IACpH,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC3C,uGAAuG;IACvG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC5D,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC1C,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,IACtF,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,GAAG;IAC5B,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;CACtC,CAAC;AAEJ,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC;IACxF,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC,qDAAqD;IACrD,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;CAC7C;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,EACtF,IAAI,EAAE,iBAAiB,CAAC,CAAC,EAAE,OAAO,CAAC,EACnC,QAAQ,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,GACtC,kBAAkB,CAAC,CAAC,CAAC,CA2BvB"}

package/dist/useOneOfField.js

@@ -0,0 +1,53 @@
+import { calculateEnabled, useFieldCore } from './field.js';
+import { getReason, getVerdict } from './decision.js';
+import { resolve } from './resolve.js';
+function resolveChoice(fieldId, choice) {
+    const decision = calculateEnabled(`${fieldId}.${choice.value}`, choice.enabled, choice.disabled);
+    const enabled = getVerdict(decision, true);
+    return {
+        value: choice.value,
+        label: choice.label ?? choice.value,
+        description: choice.description,
+        icon: choice.icon,
+        enabled,
+        whyDisabled: enabled ? undefined : getReason(decision),
+        variant: choice.variant ?? 'default',
+        group: choice.group,
+    };
+}
+/**
+ * A field whose value is one of a list of choices (moxb's OneOf). Rendered by
+ * vultus-antd's OneOfSelect and OneOfSegmented, which take the same controls.
+ * Each choice may be disabled with a reason; the field's current state is the
+ * current choice's description unless `valueDescriptions` words it
+ * differently. Requesting a disabled or unknown choice is ignored with a
+ * warning, as a disabled field ignores any request. Inside the field the value
+ * starts at `initialValue`, else at the first enabled choice.
+ */
+export function useOneOfField(opts, registry) {
+    const choices = resolve(opts.choices, []).map((c) => resolveChoice(opts.id, c));
+    const inside = !opts.onChange && !opts.commit;
+    const initialValue = opts.initialValue ?? choices.find((c) => c.enabled)?.value;
+    const field = useFieldCore('oneOf', inside ? { ...opts, initialValue } : opts, registry);
+    const current = choices.find((c) => c.value === field.value);
+    const setValue = (next) => {
+        const choice = choices.find((c) => c.value === next);
+        if (!choice) {
+            console.warn(`Field '${opts.id}': '${next}' is not one of its choices`);
+            return;
+        }
+        if (!choice.enabled) {
+            console.warn(`Field '${opts.id}': choice '${next}' is disabled — ${choice.whyDisabled ?? '(no reason)'}`);
+            return;
+        }
+        field.setValue(next);
+    };
+    return {
+        ...field,
+        valueDescription: field.valueDescription ?? current?.description,
+        setValue,
+        choices,
+        current,
+    };
+}
+//# sourceMappingURL=useOneOfField.js.map

package/dist/useOneOfField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOneOfField.js","sourceRoot":"","sources":["../src/useOneOfField.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAyC,MAAM,YAAY,CAAC;AACnG,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AA6CvC,SAAS,aAAa,CAAmB,OAAe,EAAE,MAAsB;IAC9E,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACjG,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3C,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;QACnC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO;QACP,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC;QACtD,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,SAAS;QACpC,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAmC,EACnC,QAAuC;IAEvC,MAAM,OAAO,GAAG,OAAO,CAAmB,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAClG,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAChF,MAAM,KAAK,GAAG,YAAY,CAAgB,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxG,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC;IAE7D,MAAM,QAAQ,GAAG,CAAC,IAAO,EAAE,EAAE;QAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE,OAAO,IAAI,6BAA6B,CAAC,CAAC;YACxE,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE,cAAc,IAAI,mBAAmB,MAAM,CAAC,WAAW,IAAI,aAAa,EAAE,CAAC,CAAC;YAC1G,OAAO;QACT,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,KAAK;QACR,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,IAAI,OAAO,EAAE,WAAW;QAChE,QAAQ;QACR,OAAO;QACP,OAAO;KACR,CAAC;AACJ,CAAC"}

package/package.json

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

package/src/index.ts

@@ -14,5 +14,8 @@ export { useBoolField, type BoolFieldControls, type BoolFieldOptions } from './u
 export {
   useMixedBoolField, aggregateBool, type MixedBool, type MixedBoolFieldControls, type MixedBoolFieldOptions,
 } from './useMixedBoolField.js';
+export {
+  useOneOfField, type OneOfChoice, type OneOfChoiceControls, type OneOfFieldControls, type OneOfFieldOptions,
+} from './useOneOfField.js';
 export { InternalLinkContext, useInternalLink, type InternalLinkComponent } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink, type MessageSink } from './MessageSink.js';

package/src/useOneOfField.ts

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react';
+import { calculateEnabled, useFieldCore, type FieldControls, type FieldOptions } from './field.js';
+import { getReason, getVerdict } from './decision.js';
+import { resolve } from './resolve.js';
+import type { Decision, ErrorRoutesRegistry, ValueOrFn } from './types.js';
+
+/** One choice of a one-of field (moxb's BindOneOfChoice). */
+export interface OneOfChoice<T extends string = string> {
+  value: T;
+  /** Shown for the choice; default: the value. */
+  label?: string;
+  /** What choosing it does (moxb's `help`), markdown; also the field's current state when it is chosen. */
+  description?: string;
+  /** Shown before the label (or instead of it, for an icon-only widget), like an action's icon. */
+  icon?: ReactNode;
+  /** Choosable? Default true, optionally with a reason. Use `enabled` or `disabled`, not contradicting each other. */
+  enabled?: Decision;
+  disabled?: Decision;
+  /** Shown as the main or a dangerous choice, like an action's variant. Default 'default'. */
+  variant?: 'default' | 'primary' | 'danger';
+  /** A heading the choice is listed under, after the choices without one (OneOfSelect); default none. */
+  group?: string;
+}
+
+/** A choice as the widgets get it. */
+export interface OneOfChoiceControls<T extends string = string> {
+  value: T;
+  label: string;
+  description: string | undefined;
+  icon: ReactNode | undefined;
+  enabled: boolean;
+  whyDisabled: string | undefined;
+  variant: 'default' | 'primary' | 'danger';
+  group: string | undefined;
+}
+
+export type OneOfFieldOptions<T extends string = string, RouteId extends string = string> =
+  FieldOptions<T, T, RouteId> & {
+    /** The choices, in order; static or derived. */
+    choices: ValueOrFn<OneOfChoice<T>[]>;
+  };
+
+export interface OneOfFieldControls<T extends string = string> extends FieldControls<T, T> {
+  choices: OneOfChoiceControls<T>[];
+  /** The choice the value is, if it is one of them. */
+  current: OneOfChoiceControls<T> | undefined;
+}
+
+function resolveChoice<T extends string>(fieldId: string, choice: OneOfChoice<T>): OneOfChoiceControls<T> {
+  const decision = calculateEnabled(`${fieldId}.${choice.value}`, choice.enabled, choice.disabled);
+  const enabled = getVerdict(decision, true);
+  return {
+    value: choice.value,
+    label: choice.label ?? choice.value,
+    description: choice.description,
+    icon: choice.icon,
+    enabled,
+    whyDisabled: enabled ? undefined : getReason(decision),
+    variant: choice.variant ?? 'default',
+    group: choice.group,
+  };
+}
+
+/**
+ * A field whose value is one of a list of choices (moxb's OneOf). Rendered by
+ * vultus-antd's OneOfSelect and OneOfSegmented, which take the same controls.
+ * Each choice may be disabled with a reason; the field's current state is the
+ * current choice's description unless `valueDescriptions` words it
+ * differently. Requesting a disabled or unknown choice is ignored with a
+ * warning, as a disabled field ignores any request. Inside the field the value
+ * starts at `initialValue`, else at the first enabled choice.
+ */
+export function useOneOfField<T extends string = string, RouteId extends string = string>(
+  opts: OneOfFieldOptions<T, RouteId>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): OneOfFieldControls<T> {
+  const choices = resolve<OneOfChoice<T>[]>(opts.choices, []).map((c) => resolveChoice(opts.id, c));
+  const inside = !opts.onChange && !opts.commit;
+  const initialValue = opts.initialValue ?? choices.find((c) => c.enabled)?.value;
+  const field = useFieldCore<T, T, RouteId>('oneOf', inside ? { ...opts, initialValue } : opts, registry);
+  const current = choices.find((c) => c.value === field.value);
+
+  const setValue = (next: T) => {
+    const choice = choices.find((c) => c.value === next);
+    if (!choice) {
+      console.warn(`Field '${opts.id}': '${next}' is not one of its choices`);
+      return;
+    }
+    if (!choice.enabled) {
+      console.warn(`Field '${opts.id}': choice '${next}' is disabled — ${choice.whyDisabled ?? '(no reason)'}`);
+      return;
+    }
+    field.setValue(next);
+  };
+
+  return {
+    ...field,
+    valueDescription: field.valueDescription ?? current?.description,
+    setValue,
+    choices,
+    current,
+  };
+}