vultus-core 0.4.0 → 0.5.0

package/src/numeric.ts

@@ -0,0 +1,68 @@
+import { NO_FIELD_CONTEXT, readingContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import type { ValueOrFn } from './types.js';
+
+/**
+ * The bounds and formatting a numeric field has, shared with the range kind (whose two ends
+ * reuse the same bounds). Each may be a context function, resolved like any other field option.
+ * `format` is not itself a ValueOrFn — it always takes the number as its first argument — so it
+ * is resolved by its own rule, below.
+ */
+export interface NumericBounds<Ctx = any> {
+  min?: ValueOrFn<number | undefined, Ctx>;
+  max?: ValueOrFn<number | undefined, Ctx>;
+  step?: ValueOrFn<number | undefined, Ctx>;
+  integer?: ValueOrFn<boolean, Ctx>;
+  unit?: ValueOrFn<string | undefined, Ctx>;
+  /** Formats a value for display; default: the number followed by the unit, if any. */
+  format?: (n: number, ctx: Ctx) => string;
+}
+
+/** A NumericBounds with every option resolved through the field context. */
+export interface ResolvedNumeric {
+  min: number | undefined;
+  max: number | undefined;
+  step: number | undefined;
+  integer: boolean;
+  unit: string | undefined;
+  format(n: number): string;
+}
+
+/** Clamps `n` into [min, max]; either end left out leaves that side open. */
+export function clamp(n: number, min?: number, max?: number): number {
+  let result = n;
+  if (min !== undefined) result = Math.max(result, min);
+  if (max !== undefined) result = Math.min(result, max);
+  return result;
+}
+
+/**
+ * Resolves a numeric field's bounds and formatter with the field context. `format` goes by its
+ * own rule, not resolveIn's, as it always receives the number first; otherwise it is treated
+ * the same way. With a provider above, it receives the context as its second argument, and a
+ * key it reads that no provider gave throws naming the field and the option `'format'`. With
+ * none, a `format` that declares the context parameter (`format.length >= 2`) throws the same
+ * message shape resolveIn uses, and one that does not is called with the number alone.
+ */
+export function resolveNumeric(id: string, opts: NumericBounds, ctx: FieldCtx): ResolvedNumeric {
+  const where = (name: string) => `Field '${id}': option '${name}'`;
+  const min = resolveIn<number | undefined>(opts.min, undefined, ctx, where('min'));
+  const max = resolveIn<number | undefined>(opts.max, undefined, ctx, where('max'));
+  const step = resolveIn<number | undefined>(opts.step, undefined, ctx, where('step'));
+  const integer = resolveIn<boolean>(opts.integer, false, ctx, where('integer'));
+  const unit = resolveIn<string | undefined>(opts.unit, undefined, ctx, where('unit'));
+
+  const { format } = opts;
+  let resolvedFormat: (n: number) => string;
+  if (format === undefined) {
+    resolvedFormat = (n) => `${n}${unit ?? ''}`;
+  } else if (ctx !== NO_FIELD_CONTEXT) {
+    resolvedFormat = (n) => readingContext(where('format'), () => format(n, ctx as never));
+  } else if (format.length < 2) {
+    resolvedFormat = (n) => format(n, undefined as never);
+  } else {
+    throw new Error(`${where('format')} is a function of the field context, but no FieldContextProvider is above it`);
+  }
+
+  return { min, max, step, integer, unit, format: resolvedFormat };
+}

package/src/resolve.ts

@@ -1,6 +1,29 @@
+import { NO_FIELD_CONTEXT, readingContext, type FieldCtx } from './FieldContext.js';
 import type { ValueOrFn } from './types.js';
 
 export function resolve<T>(v: ValueOrFn<T> | undefined, fallback: T): T {
   if (v === undefined) return fallback;
   return typeof v === 'function' ? (v as () => T)() : v;
 }
+
+/**
+ * Resolves a field's option with its context. With a provider above, every function receives
+ * `ctx`, so one whose parameter has a default (`(ctx = {}) => ...`) gets it too. With none, a
+ * function without declared parameters is called with nothing, so it works without a provider,
+ * and one that declares a parameter throws, `where` (`Field '<id>': option '<name>'`) saying
+ * whose it is. A key the function reads that no provider gave throws with `where` in front, so
+ * that error names the field and the option too. A function that returns `undefined` counts as
+ * an absent option, and yields `fallback` — a context lookup that misses (e.g. `(ctx) =>
+ * ctx.items[id]`) should fall back exactly as leaving the option out would, not leave the field
+ * with no value at all.
+ */
+export function resolveIn<T>(v: ValueOrFn<T> | undefined, fallback: T, ctx: FieldCtx, where: string): T {
+  if (v === undefined) return fallback;
+  if (typeof v !== 'function') return v;
+  const fn = v as (ctx?: object) => T;
+  if (ctx !== NO_FIELD_CONTEXT) return readingContext(where, () => fn(ctx)) ?? fallback;
+  if (fn.length > 0) {
+    throw new Error(`${where} is a function of the field context, but no FieldContextProvider is above it`);
+  }
+  return fn() ?? fallback;
+}

package/src/tree.ts

@@ -0,0 +1,175 @@
+import type { OneOfChoice, OneOfChoiceControls } from './choices.js';
+import { normalizeText } from './normalizeText.js';
+
+/** A node of a tree field (Praeceptor's categories): a choice with children. */
+export interface TreeNode<T extends string = string> extends OneOfChoice<T> {
+  children?: TreeNode<T>[];
+}
+
+/** A node as the widgets get it: the resolved choice, its children likewise, and whether it shows checked. */
+export interface TreeNodeControls<T extends string = string> extends OneOfChoiceControls<T> {
+  children: TreeNodeControls<T>[] | undefined;
+  /** Covered by the value (in the cascading selections), or in the value (`'independent'`). */
+  checked: boolean;
+}
+
+/**
+ * What a tree field's value lists, as antd TreeSelect's `showCheckedStrategy` and
+ * `checkStrictly` do. In the three cascading selections a node stands for its subtree, and
+ * a node all of whose children are covered is covered too; they differ only in which of the
+ * covered nodes the value names:
+ * - `'topmost'` (`SHOW_PARENT`, the default): the covered nodes whose parent is not covered;
+ * - `'all'` (`SHOW_ALL`): every covered node;
+ * - `'leaves'` (`SHOW_CHILD`): the covered leaves.
+ *
+ * `'independent'` (`checkStrictly`, moxb's `strictSelect`): each node is chosen on its own.
+ */
+export type TreeSelection = 'topmost' | 'all' | 'leaves' | 'independent';
+
+/**
+ * Which nodes a tree widget opens at first: `'top'` (the default), the roots with children;
+ * `'none'`; `'selected'` (moxb's `expandValues`), the ancestors of the value's nodes; `'all'`,
+ * every node with children.
+ */
+export type TreeExpand = 'top' | 'none' | 'selected' | 'all';
+
+function hasChildren(node: { children?: unknown[] }): boolean {
+  return (node.children?.length ?? 0) > 0;
+}
+
+/** The nodes in pre-order, and each node's parent. */
+function indexTree<T extends string>(nodes: TreeNode<T>[]): { order: TreeNode<T>[]; parent: Map<T, T> } {
+  const order: TreeNode<T>[] = [];
+  const parent = new Map<T, T>();
+  const walk = (list: TreeNode<T>[], up: T | undefined) => {
+    for (const node of list) {
+      order.push(node);
+      if (up !== undefined) parent.set(node.value, up);
+      if (node.children) walk(node.children, node.value);
+    }
+  };
+  walk(nodes, undefined);
+  return { order, parent };
+}
+
+/** The values that name no node, in their order, without duplicates (kept, so a stale value is not silently dropped). */
+function unknownValues<T extends string>(order: TreeNode<T>[], value: T[]): T[] {
+  const known = new Set(order.map((n) => n.value));
+  return [...new Set(value.filter((v) => !known.has(v)))];
+}
+
+/** The nodes a value covers in the cascading selections: the value's nodes, their descendants, and every node all of whose children are covered. */
+function cascade<T extends string>(nodes: TreeNode<T>[], value: T[]): Set<T> {
+  const listed = new Set(value);
+  const covered = new Set<T>();
+  const walk = (node: TreeNode<T>, inherited: boolean): boolean => {
+    const self = inherited || listed.has(node.value);
+    const children = (node.children ?? []).map((child) => walk(child, self));
+    const isCovered = self || (children.length > 0 && children.every(Boolean));
+    if (isCovered) covered.add(node.value);
+    return isCovered;
+  };
+  for (const node of nodes) walk(node, false);
+  return covered;
+}
+
+/** The covered nodes the value names under `selection` (see TreeSelection), in pre-order. */
+function namedNodes<T extends string>(order: TreeNode<T>[], parent: Map<T, T>, covered: Set<T>, selection: TreeSelection): T[] {
+  const named = order.filter((node) => {
+    if (!covered.has(node.value)) return false;
+    if (selection === 'leaves') return !hasChildren(node);
+    if (selection === 'topmost') {
+      const up = parent.get(node.value);
+      return up === undefined || !covered.has(up);
+    }
+    return true;
+  });
+  return named.map((node) => node.value);
+}
+
+/**
+ * A tree field's value in its canonical form under `selection` (see TreeSelection): the
+ * nodes it names in tree pre-order, followed by the values that name no node, without
+ * duplicates. With `'topmost'`, `['A1', 'A']` becomes `['A']`, and a node's children all
+ * listed become the node.
+ */
+export function normalizeTreeValue<T extends string>(nodes: TreeNode<T>[], value: T[], selection: TreeSelection): T[] {
+  const { order, parent } = indexTree(nodes);
+  const covered = selection === 'independent' ? new Set(value) : cascade(nodes, value);
+  const named = selection === 'independent'
+    ? order.filter((node) => covered.has(node.value)).map((node) => node.value)
+    : namedNodes(order, parent, covered, selection);
+  return [...named, ...unknownValues(order, value)];
+}
+
+/**
+ * Every node a tree field's value stands for, in pre-order (what an item filed under some
+ * node matches against): in the cascading selections the covered nodes (the value's nodes,
+ * their descendants, and every node all of whose children are covered); with
+ * `'independent'` the value's nodes themselves. Values that name no node follow, as in
+ * normalizeTreeValue.
+ */
+export function coveredNodes<T extends string>(nodes: TreeNode<T>[], value: T[], selection: TreeSelection = 'topmost'): T[] {
+  return normalizeTreeValue(nodes, value, selection === 'independent' ? 'independent' : 'all');
+}
+
+/**
+ * The value after flipping `node`, normalized. In the cascading selections a covered node
+ * is removed with its descendants and its ancestors (they no longer have all their
+ * children), and an uncovered one is added with its descendants; with `'independent'` the
+ * node alone is added or removed. A `node` that is not one of the nodes changes nothing.
+ */
+export function toggleTreeValue<T extends string>(nodes: TreeNode<T>[], value: T[], node: T, selection: TreeSelection): T[] {
+  const { order, parent } = indexTree(nodes);
+  const target = order.find((n) => n.value === node);
+  if (!target) return normalizeTreeValue(nodes, value, selection);
+  if (selection === 'independent') {
+    return normalizeTreeValue(nodes, value.includes(node) ? value.filter((v) => v !== node) : [...value, node], selection);
+  }
+  const covered = cascade(nodes, value);
+  const subtree = indexTree([target]).order.map((n) => n.value);
+  if (covered.has(node)) {
+    for (const v of subtree) covered.delete(v);
+    for (let up = parent.get(node); up !== undefined; up = parent.get(up)) covered.delete(up);
+  } else {
+    for (const v of subtree) covered.add(v);
+  }
+  return normalizeTreeValue(nodes, [...covered, ...unknownValues(order, value)], selection);
+}
+
+/** The nodes a tree widget opens at first under `expand` (see TreeExpand), in pre-order. */
+export function expandedTreeKeys<T extends string>(nodes: TreeNode<T>[], value: T[], expand: TreeExpand): T[] {
+  if (expand === 'none') return [];
+  if (expand === 'top') return nodes.filter(hasChildren).map((node) => node.value);
+  const { order, parent } = indexTree(nodes);
+  if (expand === 'all') return order.filter(hasChildren).map((node) => node.value);
+  const ancestors = new Set<T>();
+  for (const v of value) {
+    for (let up = parent.get(v); up !== undefined; up = parent.get(up)) ancestors.add(up);
+  }
+  return order.filter((node) => ancestors.has(node.value)).map((node) => node.value);
+}
+
+/**
+ * The nodes matching a search (Taskmaster's category search), by antd TreeSelect's rule, so a
+ * dropdown and a drawer over the same nodes agree: a node matches if its label (else its
+ * value) contains the query, ignoring accents, case and the query's surrounding spaces. A
+ * matching node stays with its whole subtree; any other node stays if one of its descendants
+ * matches, keeping only the children that stay. A node that stays with no children has
+ * `children` undefined, not an empty list. Generic over the node's shape, so the widgets can
+ * filter resolved node controls; the nodes given are not changed. An empty query returns
+ * them as they are.
+ */
+export function filterTree<N extends { label?: string; value: string; children?: N[] }>(nodes: N[], query: string): N[] {
+  const q = normalizeText(query.trim());
+  if (!q) return nodes;
+  /** The nodes of `list` that stay; `all` when an ancestor matched, so every node does. */
+  const keep = (list: N[], all: boolean): N[] => list.flatMap((node) => {
+    const matches = all || normalizeText(node.label ?? node.value).includes(q);
+    const children = keep(node.children ?? [], matches);
+    if (!matches && children.length === 0) return [];
+    if (node.children === undefined) return [node];
+    return [{ ...node, children: children.length > 0 ? children : undefined }];
+  });
+  return keep(nodes, false);
+}

package/src/types.ts

@@ -10,7 +10,16 @@ export interface FormLike {
 }
 
 export type Decision = boolean | { verdict: boolean; reason?: string };
-export type ValueOrFn<T> = T | (() => T);
+/**
+ * A value, or a function giving it, as a field's options take them. With a FieldContextProvider
+ * above, a field calls every such function with its field context (the provider's value); with
+ * none, a function without parameters is called with nothing and one that declares a parameter
+ * throws.
+ */
+export type ValueOrFn<T, Ctx = any> = T | ((ctx: Ctx) => T);
+
+/** A value, or a function of no arguments giving it, as an action's options take them: an action calls its functions with nothing. */
+export type Thunk<T> = T | (() => T);
 
 export type Severity = 'info' | 'warning' | 'error';
 
@@ -53,17 +62,29 @@ export type ConfirmationSpec =
 
 export interface ActionOptions<TArgs = void, TResult = void, RouteId extends string = string> {
   id: string;
-  label: ValueOrFn<string>;
-  icon?: ValueOrFn<React.ReactNode>;
-  variant?: ValueOrFn<'default' | 'primary' | 'danger'>;
-  enabled?: ValueOrFn<Decision>;
-  invisible?: ValueOrFn<boolean>;
-  confirmation?: ValueOrFn<ConfirmationSpec | undefined>;
+  label: Thunk<string>;
+  icon?: Thunk<React.ReactNode>;
+  variant?: Thunk<'default' | 'primary' | 'danger'>;
+  enabled?: Thunk<Decision>;
+  invisible?: Thunk<boolean>;
+  confirmation?: Thunk<ConfirmationSpec | undefined>;
   errorRoute?: RouteId;
   fire: (args: TArgs, ctx: ExecutionContext) => Promise<TResult> | TResult;
   onSuccess?: (result: TResult) => void;
 }
 
+/** Compiles only when `A` is assignable to `B`. */
+type Fits<A extends B, B> = A;
+
+/**
+ * A compile-time check: an action calls its options' functions with nothing, so one that takes
+ * a parameter (the field context, say) must not compile, rather than crash when it is called.
+ */
+type ActionFunctionsTakeNoParameter = [
+  // @ts-expect-error -- a function of a parameter is not a zero-argument thunk.
+  Fits<(ctx: { t(key: string): string }) => string, ActionOptions['label']>,
+];
+
 // Conditional rest-tuple lets call sites omit args entirely when TArgs is
 // void (e.g. plain ActionButton click) and requires the value otherwise
 // (e.g. FormSubmitButton passing typed form values).

package/src/useArg.ts

@@ -0,0 +1,121 @@
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+import type { RawChange, UpdateMethod } from './argStore.js';
+import { useArgStore } from './ArgStoreContext.js';
+import { useFieldContext } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import type { ValueOrFn } from './types.js';
+import type { ValueType } from './valueTypes.js';
+
+/** An argument's shape (moxb's url-arg definition, without a `permanent` flag — that is a router concern). */
+export interface ArgDefinition<T, Ctx = any> {
+  key: string;
+  valueType: ValueType<T>;
+  default: ValueOrFn<T, Ctx>;
+}
+
+export interface ArgControls<T> {
+  value: T;
+  isDefault: boolean;
+  set(value: T, method?: UpdateMethod): void;
+  reset(method?: UpdateMethod): void;
+  /** The href `set(value)` would produce, where the store supports it (a URL store); `undefined` otherwise. */
+  hrefFor(value: T): string | undefined;
+}
+
+/** The raw value a write needs for `value`: `undefined` (removes the key) when it equals the default, else its formatted form. */
+function rawFor<T>(value: T, defaultValue: T, valueType: ValueType<T>): string | undefined {
+  return valueType.isEqual(value, defaultValue) ? undefined : valueType.format(value);
+}
+
+/**
+ * An argument read from and written to the nearest ArgStore. An absent key reads as the default;
+ * writing the default removes the key.
+ *
+ * `parse(raw)` is memoized on `[raw, key, valueType]` (not the default, which may be a context
+ * function with its own, independently changing inputs): re-rendering with the same raw value
+ * does not re-parse and does not re-warn; a raw value that does not parse warns once per such
+ * change and the default is used instead. `value` itself then keeps its previous identity
+ * whenever it is still `isEqual` to the freshly computed one (parsed-or-default), so a default
+ * that builds a fresh value every render (`() => []`) does not change `value`'s identity either —
+ * effects keyed on `value` do not re-run just because nothing meaningful changed.
+ */
+export function useArg<T>(definition: ArgDefinition<T>): ArgControls<T> {
+  const { key, valueType, default: defaultOrFn } = definition;
+  const store = useArgStore();
+  const ctx = useFieldContext();
+  // Called on the store, not passed detached: a store written as a class uses `this`.
+  const subscribe = useCallback((listener: () => void) => store.subscribe(listener), [store]);
+  const read = useCallback(() => store.read(key), [store, key]);
+  const raw = useSyncExternalStore(subscribe, read);
+  const defaultValue = resolveIn<T>(defaultOrFn, undefined as T, ctx, `Argument '${key}': option 'default'`);
+
+  const parsed = useMemo<T | undefined>(() => {
+    if (raw === undefined) return undefined;
+    const p = valueType.parse(raw);
+    if (p === undefined) console.warn(`Argument '${key}': cannot read '${raw}', using the default`);
+    return p;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [raw, key, valueType]);
+  const candidate = parsed ?? defaultValue;
+
+  const previousRef = useRef<{ value: T } | undefined>(undefined);
+  const value = previousRef.current !== undefined && valueType.isEqual(previousRef.current.value, candidate)
+    ? previousRef.current.value
+    : candidate;
+  previousRef.current = { value };
+
+  const set = useCallback(
+    (next: T, method: UpdateMethod = 'replace') => {
+      store.write([{ key, raw: rawFor(next, defaultValue, valueType) }], method);
+    },
+    [store, key, valueType, defaultValue],
+  );
+  const reset = useCallback(
+    (method: UpdateMethod = 'replace') => {
+      store.write([{ key, raw: undefined }], method);
+    },
+    [store, key],
+  );
+  const hrefFor = useCallback(
+    (next: T): string | undefined => {
+      if (!store.hrefFor) return undefined;
+      return store.hrefFor([{ key, raw: rawFor(next, defaultValue, valueType) }]);
+    },
+    [store, key, valueType, defaultValue],
+  );
+
+  return { value, isDefault: valueType.isEqual(value, defaultValue), set, reset, hrefFor };
+}
+
+/** One argument's planned change in a batch (moxb's ArgChange): a new value, or a reset. */
+export type ArgChange = { definition: ArgDefinition<any>; value?: unknown; reset?: true };
+
+export function setArg<T>(definition: ArgDefinition<T>, value: T): ArgChange {
+  return { definition, value };
+}
+
+export function resetArg(definition: ArgDefinition<any>): ArgChange {
+  return { definition, reset: true };
+}
+
+/**
+ * Applies several argument changes as one store write (one history entry: "clear all", a chip
+ * that also closes a task). Each change's default is resolved at call time, from the field
+ * context captured when this hook rendered.
+ */
+export function useArgWriter(): (changes: ArgChange[], method?: UpdateMethod) => void {
+  const store = useArgStore();
+  const ctx = useFieldContext();
+  return useCallback(
+    (changes: ArgChange[], method: UpdateMethod = 'replace') => {
+      const rawChanges: RawChange[] = changes.map((change) => {
+        const { key, valueType, default: defaultOrFn } = change.definition;
+        if (change.reset) return { key, raw: undefined };
+        const defaultValue = resolveIn(defaultOrFn, undefined, ctx, `Argument '${key}': option 'default'`);
+        return { key, raw: rawFor(change.value, defaultValue, valueType) };
+      });
+      store.write(rawChanges, method);
+    },
+    [store, ctx],
+  );
+}

package/src/useBoolField.ts

@@ -1,7 +1,9 @@
 import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
-import type { ErrorRoutesRegistry } from './types.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import type { ErrorRoutesRegistry, ValueOrFn } from './types.js';
 
-export type BoolFieldOptions<RouteId extends string = string> = FieldOptions<boolean, boolean, RouteId>;
+export type BoolFieldOptions<RouteId extends string = string, Ctx = any> = FieldOptions<boolean, boolean, RouteId, Ctx>;
 
 export interface BoolFieldControls extends FieldControls<boolean, boolean> {
   /**
@@ -11,19 +13,30 @@ export interface BoolFieldControls extends FieldControls<boolean, boolean> {
   toggle(): void;
 }
 
+/** The implicit initial value for a boolean field: `initialValue` resolved, else false. */
+export function boolInitialValue(
+  opts: { initialValue?: ValueOrFn<boolean> },
+  ctx: FieldCtx,
+  id: string,
+): boolean {
+  return resolveIn<boolean>(opts.initialValue, false, ctx, `Field '${id}': option 'initialValue'`);
+}
+
 /**
  * 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>,
+export function useBoolField<RouteId extends string = string, Ctx = any>(
+  opts: BoolFieldOptions<RouteId, Ctx>,
   registry?: ErrorRoutesRegistry<RouteId>,
 ): BoolFieldControls {
+  const ctx = useFieldContext();
   const inside = !opts.onChange && !opts.commit;
-  const field = useFieldCore<boolean, boolean, RouteId>(
+  const initialValue = () => boolInitialValue(opts, ctx, opts.id);
+  const field = useFieldCore<boolean, boolean, RouteId, Ctx>(
     'boolean',
-    inside ? { ...opts, initialValue: opts.initialValue ?? false } : opts,
+    inside ? { ...opts, initialValue } : opts,
     registry,
   );
   return { ...field, toggle: () => field.setValue(!field.value) };

package/src/useManyOfField.ts

@@ -0,0 +1,107 @@
+import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
+import { resolveChoice, type OneOfChoice, type OneOfChoiceControls } from './choices.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import type { ErrorRoutesRegistry, ValueOrFn } from './types.js';
+
+export type ManyOfOwnOptions<T extends string = string, Ctx = any> = {
+  /** The choices, in order; static or derived (a function, of the field context if it declares a parameter). */
+  choices: ValueOrFn<OneOfChoice<T>[], Ctx>;
+};
+
+export type ManyOfFieldOptions<T extends string = string, RouteId extends string = string, Ctx = any> =
+  FieldOptions<T[], T[], RouteId, Ctx> & ManyOfOwnOptions<T, Ctx>;
+
+export interface ManyOfChoiceControls<T extends string = string> extends OneOfChoiceControls<T> {
+  selected: boolean;
+}
+
+export interface ManyOfFieldControls<T extends string = string> extends FieldControls<T[], T[]> {
+  choices: ManyOfChoiceControls<T>[];
+  isSelected(value: T): boolean;
+  /** Flips a choice's membership in the value; ignored (with a warning) for an unknown or disabled choice. */
+  toggle(value: T): void;
+}
+
+/** The implicit initial value for a many-of field: `initialValue` resolved, else the empty list. */
+export function manyOfInitialValue<T extends string>(
+  opts: { initialValue?: ValueOrFn<T[]> },
+  ctx: FieldCtx,
+  id: string,
+): T[] {
+  return resolveIn<T[]>(opts.initialValue, [], ctx, `Field '${id}': option 'initialValue'`);
+}
+
+/**
+ * A field whose value is a set of choices (moxb's ManyOf). A request (to
+ * `setValue` or `toggle`) is normalized to the known choices in their order,
+ * without duplicates, followed by the values the field already holds that are
+ * no longer among the choices and that the request keeps (in their current
+ * order: `toggle` keeps them, so a stored value naming a choice that was
+ * removed is not silently dropped, while `setValue([])` clears it). A request
+ * naming a value that is neither a choice nor already held, or that changes a
+ * disabled choice's membership, is ignored with a warning — as useOneOfField
+ * refuses a disabled or unknown choice.
+ */
+export function useManyOfField<T extends string = string, RouteId extends string = string, Ctx = any>(
+  opts: ManyOfFieldOptions<T, RouteId, Ctx>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): ManyOfFieldControls<T> {
+  const ctx = useFieldContext();
+  const resolvedChoices = resolveIn<OneOfChoice<T>[]>(opts.choices, [], ctx, `Field '${opts.id}': option 'choices'`)
+    .map((c) => resolveChoice(opts.id, c));
+  const byValue = new Map(resolvedChoices.map((c) => [c.value, c]));
+  const choiceOrder = resolvedChoices.map((c) => c.value);
+
+  const inside = !opts.onChange && !opts.commit;
+  const initialValue = () => manyOfInitialValue<T>(opts, ctx, opts.id);
+  const field = useFieldCore<T[], T[], RouteId, Ctx>('manyOf', inside ? { ...opts, initialValue } : opts, registry);
+
+  /** The normalized list a request becomes, or undefined when the request is refused (with a warning already issued). */
+  const normalize = (request: T[], current: T[]): T[] | undefined => {
+    const requestSet = new Set(request);
+    const currentSet = new Set(current);
+    const heldUnknown = current.filter((v) => !byValue.has(v));
+    const heldUnknownSet = new Set(heldUnknown);
+    for (const v of request) {
+      if (!byValue.has(v) && !heldUnknownSet.has(v)) {
+        console.warn(`Field '${opts.id}': '${v}' is not one of its choices`);
+        return undefined;
+      }
+    }
+    for (const choice of resolvedChoices) {
+      if (choice.enabled) continue;
+      if (currentSet.has(choice.value) !== requestSet.has(choice.value)) {
+        console.warn(`Field '${opts.id}': choice '${choice.value}' is disabled — ${choice.whyDisabled ?? '(no reason)'}`);
+        return undefined;
+      }
+    }
+    return [...choiceOrder.filter((v) => requestSet.has(v)), ...heldUnknown.filter((v) => requestSet.has(v))];
+  };
+
+  const setValue = (next: T[]) => {
+    const normalized = normalize(next, field.value);
+    if (normalized === undefined) return;
+    field.setValue(normalized);
+  };
+
+  const isSelected = (value: T): boolean => field.value.includes(value);
+
+  const toggle = (value: T) => {
+    const choice = byValue.get(value);
+    if (!choice) {
+      console.warn(`Field '${opts.id}': '${value}' is not one of its choices`);
+      return;
+    }
+    if (!choice.enabled) {
+      console.warn(`Field '${opts.id}': choice '${value}' is disabled — ${choice.whyDisabled ?? '(no reason)'}`);
+      return;
+    }
+    const current = field.value;
+    setValue(current.includes(value) ? current.filter((v) => v !== value) : [...current, value]);
+  };
+
+  const choices: ManyOfChoiceControls<T>[] = resolvedChoices.map((c) => ({ ...c, selected: field.value.includes(c.value) }));
+
+  return { ...field, setValue, choices, isSelected, toggle };
+}

package/src/useMixedBoolField.ts

@@ -1,16 +1,27 @@
 import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
-import type { ErrorRoutesRegistry } from './types.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import type { ErrorRoutesRegistry, ValueOrFn } 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 type MixedBoolFieldOptions<RouteId extends string = string, Ctx = any> = FieldOptions<MixedBool, boolean, RouteId, Ctx>;
 
 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;
 }
 
+/** The implicit initial value for a mixed-boolean field: `initialValue` resolved, else false. */
+export function mixedBoolInitialValue(
+  opts: { initialValue?: ValueOrFn<MixedBool> },
+  ctx: FieldCtx,
+  id: string,
+): MixedBool {
+  return resolveIn<MixedBool>(opts.initialValue, false, ctx, `Field '${id}': option 'initialValue'`);
+}
+
 /**
  * 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
@@ -18,14 +29,16 @@ export interface MixedBoolFieldControls extends FieldControls<MixedBool, boolean
  * 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>,
+export function useMixedBoolField<RouteId extends string = string, Ctx = any>(
+  opts: MixedBoolFieldOptions<RouteId, Ctx>,
   registry?: ErrorRoutesRegistry<RouteId>,
 ): MixedBoolFieldControls {
+  const ctx = useFieldContext();
   const inside = !opts.onChange && !opts.commit;
-  const field = useFieldCore<MixedBool, boolean, RouteId>(
+  const initialValue = () => mixedBoolInitialValue(opts, ctx, opts.id);
+  const field = useFieldCore<MixedBool, boolean, RouteId, Ctx>(
     'mixed-boolean',
-    inside ? { ...opts, initialValue: opts.initialValue ?? false } : opts,
+    inside ? { ...opts, initialValue } : opts,
     registry,
   );
   return { ...field, toggle: () => field.setValue(field.value !== true) };