vultus-core 0.2.1 → 0.4.0

package/README.md

@@ -22,8 +22,10 @@ npm install vultus-core
   `parseApiError`, `routeApiError`, `ActionErrorContext` / `useActionErrorCtx`,
   `useAction`, `useActionList`, the fields (`useBoolField`, `useFieldCore` and
   their types), `InternalLinkContext` / `useInternalLink` /
-  `InternalLinkComponent`, and `MessageSinkContext` / `useMessageSink` /
-  `MessageSink`.
+  `InternalLinkComponent`, `MessageSinkContext` / `useMessageSink` /
+  `MessageSink`, and `VultusComponentsContext` / `useVultusComponents` /
+  `SpinnerScope` / `useSpinnerKey` / `VultusComponents` / `SpinnerProps` /
+  `SpinnerComponent`.
 - `./link` — `InternalLinkContext`, `useInternalLink`, and the
   `InternalLinkComponent` type on their own, for consumers that only need the
   link-injection seam.
@@ -61,6 +63,31 @@ 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.
+
+## Components
+
+`VultusComponentsContext` (default `{}`) / `useVultusComponents()` is how an app lends its own
+UI to vultus/optio in place of their native indicators — today just `Spinner` (`SpinnerProps`:
+`spinnerKey`, `size?`, `label?`; `VultusComponents.Spinner?: SpinnerComponent`). vultus-antd's
+`VultusProvider` merges a `components` prop into the outer context value; without one, the
+outer value (or this default) applies, as `linkComponent` does today.
+
+Every call site that may render a lent `Spinner` asks for its key through `useSpinnerKey(localKey)`
+rather than hardcoding it, so an app can scope a whole subtree's keys to one instance:
+`<SpinnerScope name="optio:process:p1">` makes every `useSpinnerKey` call inside it return
+`'optio:process:p1/' + localKey`; scopes nest by joining names with `/`, outermost first.
+Library-local keys are namespaced (`vultus:...`, `optio:...`) so they never collide with an
+app's own keys.
+
 ## Distribution
 
 This package ships compiled ESM (`dist/`) with TypeScript declarations to

package/dist/Components.d.ts

@@ -0,0 +1,30 @@
+import { type ComponentType, type ReactNode } from 'react';
+/** A spinner an app lends to vultus/optio, rendered in place of their native loading indicators. */
+export interface SpinnerProps {
+    /** The spinner's identity: stable across re-renders and remounts, unique on the page (after scoping). */
+    spinnerKey: string;
+    /** antd's names (the height of antd's Spin indicator) or a height in px. */
+    size?: 'small' | 'default' | 'large' | number;
+    /** Accessible label; the spinner's own default when omitted. */
+    label?: string;
+}
+export type SpinnerComponent = ComponentType<SpinnerProps>;
+/** Components an app lends to the libraries. */
+export interface VultusComponents {
+    Spinner?: SpinnerComponent;
+}
+/**
+ * The components an app lends to vultus/optio in place of their own UI. Default is `{}`
+ * (none lent) so vultus-core stays framework-neutral; vultus-antd's `VultusProvider` merges
+ * in whatever an app passes as `components`.
+ */
+export declare const VultusComponentsContext: import("react").Context<VultusComponents>;
+export declare function useVultusComponents(): VultusComponents;
+/** Prefixes every spinner key below with `name` (scopes nest: outer/inner). */
+export declare function SpinnerScope({ name, children }: {
+    name: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** The scoped key for a library-local key: 'outer/inner/local', or 'local' outside any scope. */
+export declare function useSpinnerKey(localKey: string): string;
+//# sourceMappingURL=Components.d.ts.map

package/dist/Components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Components.d.ts","sourceRoot":"","sources":["../src/Components.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE/F,oGAAoG;AACpG,MAAM,WAAW,YAAY;IAC3B,yGAAyG;IACzG,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAC9C,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;AAE3D,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,2CAAsC,CAAC;AAE3E,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD;AAKD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BAOtF;AAED,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtD"}

package/dist/Components.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+/**
+ * The components an app lends to vultus/optio in place of their own UI. Default is `{}`
+ * (none lent) so vultus-core stays framework-neutral; vultus-antd's `VultusProvider` merges
+ * in whatever an app passes as `components`.
+ */
+export const VultusComponentsContext = createContext({});
+export function useVultusComponents() {
+    return useContext(VultusComponentsContext);
+}
+/** The scope path (segment names, outermost first) that `useSpinnerKey` prefixes onto local keys. */
+const SpinnerScopeContext = createContext([]);
+/** Prefixes every spinner key below with `name` (scopes nest: outer/inner). */
+export function SpinnerScope({ name, children }) {
+    const outer = useContext(SpinnerScopeContext);
+    // Memoized so consumers below (useSpinnerKey, via SpinnerScopeContext) don't re-render
+    // on every SpinnerScope re-render — only when the scope path actually changes. Matters
+    // once whole conversation views sit inside a SpinnerScope.
+    const scope = useMemo(() => [...outer, name], [outer, name]);
+    return _jsx(SpinnerScopeContext.Provider, { value: scope, children: children });
+}
+/** The scoped key for a library-local key: 'outer/inner/local', or 'local' outside any scope. */
+export function useSpinnerKey(localKey) {
+    const scope = useContext(SpinnerScopeContext);
+    return [...scope, localKey].join('/');
+}
+//# sourceMappingURL=Components.js.map

package/dist/Components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Components.js","sourceRoot":"","sources":["../src/Components.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAsC,MAAM,OAAO,CAAC;AAkB/F;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,aAAa,CAAmB,EAAE,CAAC,CAAC;AAE3E,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,CAAC,uBAAuB,CAAC,CAAC;AAC7C,CAAC;AAED,qGAAqG;AACrG,MAAM,mBAAmB,GAAG,aAAa,CAAW,EAAE,CAAC,CAAC;AAExD,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAA0C;IACrF,MAAM,KAAK,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAC9C,uFAAuF;IACvF,uFAAuF;IACvF,2DAA2D;IAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAC7D,OAAO,KAAC,mBAAmB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAgC,CAAC;AAC/F,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,KAAK,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC"}

package/dist/index.d.ts

@@ -9,6 +9,8 @@ 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';
+export { VultusComponentsContext, useVultusComponents, SpinnerScope, useSpinnerKey, type VultusComponents, type SpinnerProps, type SpinnerComponent, } from './Components.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;AACxF,OAAO,EACL,uBAAuB,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EACzE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,GAChE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -9,6 +9,8 @@ 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';
+export { VultusComponentsContext, useVultusComponents, SpinnerScope, useSpinnerKey, } from './Components.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;AACxF,OAAO,EACL,uBAAuB,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,GAE1E,MAAM,iBAAiB,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.4.0",
   "license": "Apache-2.0",
   "description": "Framework-neutral action model + hooks for vultus (antd-free by design)",
   "repository": {

package/src/Components.tsx

@@ -0,0 +1,47 @@
+import { createContext, useContext, useMemo, type ComponentType, type ReactNode } from 'react';
+
+/** A spinner an app lends to vultus/optio, rendered in place of their native loading indicators. */
+export interface SpinnerProps {
+  /** The spinner's identity: stable across re-renders and remounts, unique on the page (after scoping). */
+  spinnerKey: string;
+  /** antd's names (the height of antd's Spin indicator) or a height in px. */
+  size?: 'small' | 'default' | 'large' | number;
+  /** Accessible label; the spinner's own default when omitted. */
+  label?: string;
+}
+export type SpinnerComponent = ComponentType<SpinnerProps>;
+
+/** Components an app lends to the libraries. */
+export interface VultusComponents {
+  Spinner?: SpinnerComponent;
+}
+
+/**
+ * The components an app lends to vultus/optio in place of their own UI. Default is `{}`
+ * (none lent) so vultus-core stays framework-neutral; vultus-antd's `VultusProvider` merges
+ * in whatever an app passes as `components`.
+ */
+export const VultusComponentsContext = createContext<VultusComponents>({});
+
+export function useVultusComponents(): VultusComponents {
+  return useContext(VultusComponentsContext);
+}
+
+/** The scope path (segment names, outermost first) that `useSpinnerKey` prefixes onto local keys. */
+const SpinnerScopeContext = createContext<string[]>([]);
+
+/** Prefixes every spinner key below with `name` (scopes nest: outer/inner). */
+export function SpinnerScope({ name, children }: { name: string; children?: ReactNode }) {
+  const outer = useContext(SpinnerScopeContext);
+  // Memoized so consumers below (useSpinnerKey, via SpinnerScopeContext) don't re-render
+  // on every SpinnerScope re-render — only when the scope path actually changes. Matters
+  // once whole conversation views sit inside a SpinnerScope.
+  const scope = useMemo(() => [...outer, name], [outer, name]);
+  return <SpinnerScopeContext.Provider value={scope}>{children}</SpinnerScopeContext.Provider>;
+}
+
+/** The scoped key for a library-local key: 'outer/inner/local', or 'local' outside any scope. */
+export function useSpinnerKey(localKey: string): string {
+  const scope = useContext(SpinnerScopeContext);
+  return [...scope, localKey].join('/');
+}

package/src/index.ts

@@ -14,5 +14,12 @@ 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';
+export {
+  VultusComponentsContext, useVultusComponents, SpinnerScope, useSpinnerKey,
+  type VultusComponents, type SpinnerProps, type SpinnerComponent,
+} from './Components.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,
+  };
+}