vultus-core 0.4.0 → 0.5.1

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

package/src/useNumericField.ts

@@ -0,0 +1,66 @@
+import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import { clamp, fit as fitNumber, resolveNumeric, type NumericBounds, type ResolvedNumeric } from './numeric.js';
+import type { ErrorRoutesRegistry } from './types.js';
+
+export type NumericOwnOptions<Ctx = any> = NumericBounds<Ctx>;
+
+export type NumericFieldOptions<RouteId extends string = string, Ctx = any> =
+  FieldOptions<number, number, RouteId, Ctx> & NumericOwnOptions<Ctx>;
+
+export interface NumericFieldControls extends FieldControls<number, number>, ResolvedNumeric {
+  /** The value, formatted (default: the number and the unit; `format` overrides it). */
+  valueText: string;
+}
+
+/**
+ * The implicit initial value for a numeric field: `initialValue` resolved, else `min` (or 0),
+ * clamped into the bounds. Only those options are resolved, not `format`, so a `format` of the
+ * field context needs no provider here.
+ */
+export function numericInitialValue(opts: NumericFieldOptions, ctx: FieldCtx, id: string): number {
+  const resolved = resolveIn<number | undefined>(opts.initialValue, undefined, ctx, `Field '${id}': option 'initialValue'`);
+  if (resolved !== undefined) return resolved;
+  const min = resolveIn<number | undefined>(opts.min, undefined, ctx, `Field '${id}': option 'min'`);
+  const max = resolveIn<number | undefined>(opts.max, undefined, ctx, `Field '${id}': option 'max'`);
+  return clamp(min ?? 0, min, max);
+}
+
+/**
+ * A field whose value is a single number (moxb's Numeric). The shown value is always clamped
+ * into the bounds, then rounded when `integer`, since a value from outside (a stored or
+ * passed-in one) may fall outside them or be fractional even when every request this hook makes
+ * fits. A request is clamped and rounded the same way; a non-finite request (e.g. a widget
+ * parsing `''`) is refused with a warning, as a disabled field refuses any request.
+ */
+export function useNumericField<RouteId extends string = string, Ctx = any>(
+  opts: NumericFieldOptions<RouteId, Ctx>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): NumericFieldControls {
+  const ctx = useFieldContext();
+  const resolved = resolveNumeric(opts.id, opts, ctx);
+  const inside = !opts.onChange && !opts.commit;
+  const initialValue = () => numericInitialValue(opts, ctx, opts.id);
+  const field = useFieldCore<number, number, RouteId, Ctx>('numeric', inside ? { ...opts, initialValue } : opts, registry);
+
+  /** A number clamped into the bounds, then rounded when `integer`. */
+  const fit = (n: number) => fitNumber(n, resolved.min, resolved.max, resolved.integer);
+  const value = fit(field.value);
+
+  const setValue = (next: number) => {
+    if (!Number.isFinite(next)) {
+      console.warn(`Field '${opts.id}': '${next}' is not a finite number`);
+      return;
+    }
+    field.setValue(fit(next));
+  };
+
+  return {
+    ...field,
+    ...resolved,
+    value,
+    setValue,
+    valueText: resolved.format(value),
+  };
+}

package/src/useOneOfField.ts

@@ -1,44 +1,36 @@
-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';
+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';
 
-/** 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;
-}
+// Re-exported so today's callers (`import { type OneOfChoice } from 'vultus-core'`, and tests
+// importing from this file) keep working now that the choice types live in choices.ts.
+export type { OneOfChoice, OneOfChoiceControls };
 
-/** 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 OneOfOwnOptions<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 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 type OneOfFieldOptions<T extends string = string, RouteId extends string = string, Ctx = any> =
+  FieldOptions<T, T, RouteId, Ctx> & OneOfOwnOptions<T, Ctx>;
+
+/**
+ * The implicit initial value for a one-of field: `initialValue` resolved through the field
+ * context, else the first enabled choice. Resolving first (rather than `opts.initialValue ??
+ * ...`) matters when `initialValue` is a context function that returns undefined: `??` would
+ * see the function, not its result, and never fall back.
+ */
+export function oneOfInitialValue<T extends string>(
+  opts: { initialValue?: ValueOrFn<T> },
+  ctx: FieldCtx,
+  id: string,
+  choices: OneOfChoiceControls<T>[],
+): T | undefined {
+  const resolved = resolveIn<T | undefined>(opts.initialValue, undefined, ctx, `Field '${id}': option 'initialValue'`);
+  return resolved ?? choices.find((c) => c.enabled)?.value;
+}
 
 export interface OneOfFieldControls<T extends string = string> extends FieldControls<T, T> {
   choices: OneOfChoiceControls<T>[];
@@ -46,21 +38,6 @@ export interface OneOfFieldControls<T extends string = string> extends FieldCont
   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.
@@ -70,14 +47,17 @@ function resolveChoice<T extends string>(fieldId: string, choice: OneOfChoice<T>
  * 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>,
+export function useOneOfField<T extends string = string, RouteId extends string = string, Ctx = any>(
+  opts: OneOfFieldOptions<T, RouteId, Ctx>,
   registry?: ErrorRoutesRegistry<RouteId>,
 ): OneOfFieldControls<T> {
-  const choices = resolve<OneOfChoice<T>[]>(opts.choices, []).map((c) => resolveChoice(opts.id, c));
+  const ctx = useFieldContext();
+  const choices = resolveIn<OneOfChoice<T>[]>(opts.choices, [], ctx, `Field '${opts.id}': option '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);
+  // Undefined when no choice is enabled, and then so is the value.
+  const initialValue = () => oneOfInitialValue(opts, ctx, opts.id, choices) as T;
+  const field = useFieldCore<T, T, RouteId, Ctx>('oneOf', inside ? { ...opts, initialValue } : opts, registry);
   const current = choices.find((c) => c.value === field.value);
 
   const setValue = (next: T) => {

package/src/useRangeField.ts

@@ -0,0 +1,83 @@
+import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import { fit as fitNumber, resolveNumeric, type NumericBounds, type ResolvedNumeric } from './numeric.js';
+import type { ErrorRoutesRegistry, ValueOrFn } from './types.js';
+
+/** A `[from, to]` pair, `from <= to`. Not named `Range`, which would shadow the DOM's global type. */
+export type NumberRange = [number, number];
+
+export type RangeOwnOptions<Ctx = any> = NumericBounds<Ctx> & { min: ValueOrFn<number, Ctx>; max: ValueOrFn<number, Ctx> };
+
+export type RangeFieldOptions<RouteId extends string = string, Ctx = any> =
+  FieldOptions<NumberRange, NumberRange, RouteId, Ctx> & RangeOwnOptions<Ctx>;
+
+export interface RangeFieldControls extends FieldControls<NumberRange, NumberRange>, ResolvedNumeric {
+  min: number;
+  max: number;
+  /** The value, formatted (default: each end's number, joined by an en dash). */
+  valueText: string;
+}
+
+function order([from, to]: NumberRange): NumberRange {
+  return from <= to ? [from, to] : [to, from];
+}
+
+/**
+ * The implicit initial value for a range field: `initialValue` resolved, else `[min, max]`. Only
+ * those options are resolved, not `format`, so a `format` of the field context needs no
+ * provider here.
+ */
+export function rangeInitialValue(opts: RangeFieldOptions, ctx: FieldCtx, id: string): NumberRange {
+  const resolved = resolveIn<NumberRange | undefined>(opts.initialValue, undefined, ctx, `Field '${id}': option 'initialValue'`);
+  if (resolved !== undefined) return resolved;
+  const min = resolveIn<number | undefined>(opts.min, undefined, ctx, `Field '${id}': option 'min'`);
+  const max = resolveIn<number | undefined>(opts.max, undefined, ctx, `Field '${id}': option 'max'`);
+  return [min as number, max as number];
+}
+
+/**
+ * A field whose value is a `[from, to]` number range (Praeceptor's school-years filter),
+ * reusing numeric's bounds and formatting; `min` and `max` are required here, and `step`
+ * defaults to 1. The shown value is each end clamped into the bounds and rounded when
+ * `integer`, then ordered, since a value from outside (a stored or passed-in one) may fall
+ * outside them, be fractional or be out of order even when every request this hook makes fits.
+ * A request is clamped, rounded and ordered the same way; a non-finite end refuses the request
+ * with a warning, as a disabled field refuses any request.
+ */
+export function useRangeField<RouteId extends string = string, Ctx = any>(
+  opts: RangeFieldOptions<RouteId, Ctx>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): RangeFieldControls {
+  const ctx = useFieldContext();
+  const resolved = resolveNumeric(opts.id, opts, ctx);
+  const min = resolved.min as number;
+  const max = resolved.max as number;
+  const step = resolved.step ?? 1;
+  const inside = !opts.onChange && !opts.commit;
+  const initialValue = () => rangeInitialValue(opts, ctx, opts.id);
+  const field = useFieldCore<NumberRange, NumberRange, RouteId, Ctx>('range', inside ? { ...opts, initialValue } : opts, registry);
+
+  /** An end clamped into the bounds, then rounded when `integer`. */
+  const fit = (n: number) => fitNumber(n, min, max, resolved.integer);
+  const value = order([fit(field.value[0]), fit(field.value[1])]);
+
+  const setValue = (next: NumberRange) => {
+    if (!Number.isFinite(next[0]) || !Number.isFinite(next[1])) {
+      console.warn(`Field '${opts.id}': '${next}' is not a finite number range`);
+      return;
+    }
+    field.setValue(order([fit(next[0]), fit(next[1])]));
+  };
+
+  return {
+    ...field,
+    ...resolved,
+    min,
+    max,
+    step,
+    value,
+    setValue,
+    valueText: `${resolved.format(value[0])}–${resolved.format(value[1])}`,
+  };
+}