vultus-core 0.4.0 → 0.5.0

package/src/useNumericField.ts

@@ -0,0 +1,69 @@
+import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import { clamp, 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) => {
+    const clamped = clamp(n, resolved.min, resolved.max);
+    return resolved.integer ? Math.round(clamped) : clamped;
+  };
+  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,86 @@
+import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import { clamp, 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) => {
+    const clamped = clamp(n, min, max);
+    return resolved.integer ? Math.round(clamped) : clamped;
+  };
+  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])}`,
+  };
+}

package/src/useStoredField.ts

@@ -0,0 +1,205 @@
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+import type { UpdateMethod } from './argStore.js';
+import { useArgStore } from './ArgStoreContext.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { initialValueOf, sanitizeStored, valueTypeOf, type FieldDefinition } from './kinds.js';
+import { useArg, type ArgDefinition } from './useArg.js';
+import type { ValueType } from './valueTypes.js';
+
+/**
+ * The argument a field's value is stored as: the definition's `id` as key, its kind's value
+ * type, and its initial value, resolved with the field context, as default — a value, so the
+ * argument layer compares against the same default the field starts at. A mixed-boolean field
+ * shows an aggregate of other data and cannot be stored: it throws, naming the field.
+ */
+export function argOf(definition: FieldDefinition, ctx: FieldCtx): ArgDefinition<any> {
+  const { id, kind } = definition;
+  let valueType: ValueType<any>;
+  try {
+    valueType = valueTypeOf(kind);
+  } catch (error) {
+    throw new Error(`Field '${id}': ${(error as Error).message}`);
+  }
+  return { key: id, valueType, default: initialValueOf(definition, ctx) };
+}
+
+function silently(_message: string): void {}
+
+function warnOnConsole(message: string): void {
+  console.warn(message);
+}
+
+/**
+ * The same value element by element: a list in the same order, a range with the same ends, a
+ * scalar. Stricter than the value types' `isEqual` (lists as sets), because the order a field
+ * shows (choice order, tree order) matters to the identity kept below.
+ */
+function sameValue(a: unknown, b: unknown): boolean {
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => v === b[i]);
+  return a === b;
+}
+
+/**
+ * Whether a field shows its default: its stored value (parsed, or the default where absent or
+ * unreadable) equals it, or fits the definition only as the default (a one-of value no longer
+ * among the choices, a range clamped to bounds that are the default). `shown` is the sanitized
+ * value, asked for only when the first test fails.
+ */
+function showsDefault(arg: ArgDefinition<any>, stored: unknown, shown: () => unknown): boolean {
+  return arg.valueType.isEqual(stored, arg.default) || arg.valueType.isEqual(shown(), arg.default);
+}
+
+/**
+ * A field kept in the nearest ArgStore: its options for the kind's hook, and whether it shows
+ * its default. `options` follows `D` member by member, so options of a definition typed as the
+ * FieldDefinition union still narrow by `kind`.
+ */
+export interface StoredField<D extends FieldDefinition = FieldDefinition> {
+  /** The definition in its outside form, for the kind's hook (`useManyOfField(stored.options)`). */
+  options: D extends any ? Omit<D, 'initialValue'> & { value: any; onChange(value: any): void } : never;
+  isDefault: boolean;
+  /** Removes the field's key from the store, so it shows its default again. */
+  reset(method?: UpdateMethod): void;
+}
+
+/** A compile-time check: options of a FieldDefinition-typed definition narrow by `kind` (the Omit distributes over the union). */
+function optionsNarrowByKind(stored: StoredField<FieldDefinition>): unknown {
+  return stored.options.kind === 'manyOf' ? stored.options.choices : undefined;
+}
+
+/**
+ * A field whose value lives in the nearest ArgStore (the URL, localStorage) under its `id`,
+ * with its initial value as the default (see argOf). `options.value` is the stored value made
+ * fit for the definition as it is now (sanitizeStored: choices, nodes and bounds follow the
+ * data); `onChange` writes with `'replace'`.
+ *
+ * A stored value that does not fit warns once per field and raw value: not again when only the
+ * definition or the field context is a new object (a provider given `value={{...}}` makes one
+ * on every render). With the key absent the default is the definer's, not stored input, and is
+ * sanitized silently.
+ *
+ * `options.value` keeps its identity while it stays the same element by element, so a list
+ * does not become a new array on every render (effects keyed on it would re-run), even when
+ * the field context is a new object each time. The default keeps its identity while it is
+ * `isEqual` to the freshly resolved one, so `onChange` and `options` keep theirs too.
+ */
+export function useStoredField<D extends FieldDefinition>(definition: D): StoredField<D> {
+  const store = useArgStore();
+  const ctx = useFieldContext();
+
+  const fresh = argOf(definition, ctx);
+  const argRef = useRef<ArgDefinition<any> | undefined>(undefined);
+  const previousArg = argRef.current;
+  const arg = previousArg !== undefined && previousArg.key === fresh.key && previousArg.valueType === fresh.valueType
+    && fresh.valueType.isEqual(previousArg.default, fresh.default)
+    ? previousArg
+    : fresh;
+  argRef.current = arg;
+
+  const { value: stored, set, reset } = useArg(arg);
+  // 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(definition.id), [store, definition.id]);
+  const raw = useSyncExternalStore(subscribe, read);
+
+  const warnedRef = useRef<string | undefined>(undefined);
+  const sanitized = useMemo(() => {
+    const input = raw === undefined ? undefined : JSON.stringify([definition.id, raw]);
+    const warn = input !== undefined && input !== warnedRef.current ? warnOnConsole : silently;
+    warnedRef.current = input;
+    return sanitizeStored(definition, stored, ctx, warn);
+  }, [definition, stored, ctx, raw]);
+
+  const previousRef = useRef<{ value: unknown } | undefined>(undefined);
+  const value = previousRef.current !== undefined && sameValue(previousRef.current.value, sanitized)
+    ? previousRef.current.value
+    : sanitized;
+  previousRef.current = { value };
+
+  const onChange = useCallback((next: unknown) => set(next, 'replace'), [set]);
+  const options = useMemo(() => {
+    const { initialValue: _inside, ...rest } = definition;
+    return { ...rest, value, onChange } as StoredField<D>['options'];
+  }, [definition, value, onChange]);
+
+  return { options, isDefault: showsDefault(arg, stored, () => value), reset };
+}
+
+/** Several stored fields at once: "more filters (3)" and "clear all". */
+export interface StoredFields {
+  /** Whether the field with this id shows its default; an id not among the fields throws. */
+  isDefault(id: string): boolean;
+  /** How many of the fields do not show their defaults. */
+  changedCount: number;
+  /** Removes every field's key in one store write (one history entry). */
+  resetAll(method?: UpdateMethod): void;
+}
+
+/** A compile-time check: useStoredFields takes a `readonly` list of definitions (an `as const` module constant). */
+function takesReadonlyDefinitions(definitions: readonly FieldDefinition[]): Parameters<typeof useStoredFields>[0] {
+  return definitions;
+}
+
+/** One field's answer in useStoredFields, with what it was computed from. */
+interface FieldReading {
+  definition: FieldDefinition;
+  raw: string | null;
+  ctx: FieldCtx;
+  isDefault: boolean;
+}
+
+/** Whether a field with this raw value shows its default, by useStoredField's rule; silent, as a summary does not warn. */
+function readsAsDefault(definition: FieldDefinition, raw: string | null, ctx: FieldCtx): boolean {
+  const arg = argOf(definition, ctx);
+  const stored = (raw === null ? undefined : arg.valueType.parse(raw)) ?? arg.default;
+  return showsDefault(arg, stored, () => sanitizeStored(definition, stored, ctx, silently));
+}
+
+/**
+ * Whether stored fields show their defaults, by the same rule as useStoredField, with one store
+ * subscription for all of them: its snapshot is their raw values joined into one string, which
+ * changes exactly when one of them does. It is a summary, so it never warns (the fields do).
+ * Each field is re-read only when its raw value, its definition or the field context changes,
+ * so typing into one field does not re-read its siblings.
+ */
+export function useStoredFields(definitions: readonly FieldDefinition[]): StoredFields {
+  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 readAll = useCallback(() => JSON.stringify(definitions.map((d) => store.read(d.id) ?? null)), [store, definitions]);
+  const snapshot = useSyncExternalStore(subscribe, readAll);
+
+  const readingsRef = useRef(new Map<string, FieldReading>());
+  const changed = useMemo(() => {
+    const raws = JSON.parse(snapshot) as (string | null)[];
+    const previous = readingsRef.current;
+    const readings = new Map<string, FieldReading>();
+    definitions.forEach((definition, i) => {
+      const raw = raws[i];
+      const before = previous.get(definition.id);
+      const reading: FieldReading = before !== undefined && before.definition === definition && before.raw === raw && before.ctx === ctx
+        ? before
+        : { definition, raw, ctx, isDefault: readsAsDefault(definition, raw, ctx) };
+      readings.set(definition.id, reading);
+    });
+    readingsRef.current = readings;
+    return new Set([...readings.values()].filter((r) => !r.isDefault).map((r) => r.definition.id));
+  }, [snapshot, definitions, ctx]);
+
+  const isDefault = useCallback(
+    (id: string) => {
+      if (!definitions.some((d) => d.id === id)) throw new Error(`Field '${id}': not among the fields given to useStoredFields`);
+      return !changed.has(id);
+    },
+    [definitions, changed],
+  );
+  const resetAll = useCallback(
+    (method: UpdateMethod = 'replace') => {
+      store.write(definitions.map((d) => ({ key: d.id, raw: undefined })), method);
+    },
+    [store, definitions],
+  );
+
+  return { isDefault, changedCount: changed.size, resetAll };
+}

package/src/useTextField.ts

@@ -0,0 +1,39 @@
+import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import type { ErrorRoutesRegistry, ValueOrFn } from './types.js';
+
+export type TextOwnOptions = { control?: 'input' | 'textarea' };
+
+export type TextFieldOptions<RouteId extends string = string, Ctx = any> =
+  FieldOptions<string, string, RouteId, Ctx> & TextOwnOptions;
+
+export interface TextFieldControls extends FieldControls<string, string> {
+  control: 'input' | 'textarea';
+}
+
+/** The implicit initial value for a text field: `initialValue` resolved, else the empty string. */
+export function textInitialValue(
+  opts: { initialValue?: ValueOrFn<string> },
+  ctx: FieldCtx,
+  id: string,
+): string {
+  return resolveIn<string>(opts.initialValue, '', ctx, `Field '${id}': option 'initialValue'`);
+}
+
+/**
+ * A field whose value is a string (moxb's Text, TextAnt, TextSearchAnt). `control` says whether
+ * vultus-antd renders an input or a textarea; defaults to `'input'`. A field inside the field or
+ * changed locally requests on every change; one that commits holds requests back until the
+ * widget decides (blur or Enter), as any commit-mode field does.
+ */
+export function useTextField<RouteId extends string = string, Ctx = any>(
+  opts: TextFieldOptions<RouteId, Ctx>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): TextFieldControls {
+  const ctx = useFieldContext();
+  const inside = !opts.onChange && !opts.commit;
+  const initialValue = () => textInitialValue(opts, ctx, opts.id);
+  const field = useFieldCore<string, string, RouteId, Ctx>('text', inside ? { ...opts, initialValue } : opts, registry);
+  return { ...field, control: opts.control ?? 'input' };
+}

package/src/useTreeField.ts

@@ -0,0 +1,108 @@
+import { useFieldCore, type FieldControls, type FieldOptions } from './field.js';
+import { resolveChoice } from './choices.js';
+import { useFieldContext, type FieldCtx } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import {
+  coveredNodes, expandedTreeKeys, normalizeTreeValue, toggleTreeValue,
+  type TreeExpand, type TreeNode, type TreeNodeControls, type TreeSelection,
+} from './tree.js';
+import type { ErrorRoutesRegistry, ValueOrFn } from './types.js';
+
+export type TreeOwnOptions<T extends string = string, Ctx = any> = {
+  /** The roots, each with its children; static or derived (a function, of the field context if it declares a parameter). */
+  nodes: ValueOrFn<TreeNode<T>[], Ctx>;
+  /** What the value lists; default `'topmost'` (see TreeSelection). */
+  selection?: TreeSelection;
+  /** Which nodes a widget opens at first; default `'top'` (see TreeExpand). */
+  expand?: TreeExpand;
+};
+
+export type TreeFieldOptions<T extends string = string, RouteId extends string = string, Ctx = any> =
+  FieldOptions<T[], T[], RouteId, Ctx> & TreeOwnOptions<T, Ctx>;
+
+export interface TreeFieldControls<T extends string = string> extends FieldControls<T[], T[]> {
+  /** The roots as the widgets get them, each with its children. */
+  nodes: TreeNodeControls<T>[];
+  selection: TreeSelection;
+  /** The nodes a widget opens at first (from `expand`). */
+  expandedKeys: T[];
+  /** Every node, by its value. */
+  byValue: Map<T, TreeNodeControls<T>>;
+  /** Checks or unchecks a node (with its subtree, in the cascading selections); ignored (with a warning) for an unknown or disabled node. */
+  toggle(value: T): void;
+}
+
+/** The implicit initial value for a tree field: `initialValue` resolved, else the empty list. */
+export function treeInitialValue<T extends string>(
+  opts: { initialValue?: ValueOrFn<T[]> },
+  ctx: FieldCtx,
+  id: string,
+): T[] {
+  return resolveIn<T[]>(opts.initialValue, [], ctx, `Field '${id}': option 'initialValue'`);
+}
+
+function sameList<T>(a: T[], b: T[]): boolean {
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+
+/**
+ * A field whose value is a set of tree nodes (Praeceptor's category filter), with antd
+ * TreeSelect's semantics: in the cascading selections a checked node stands for its subtree,
+ * and `selection` says which nodes the value lists (see TreeSelection). The value is shown
+ * and requested normalized (normalizeTreeValue): in tree pre-order, values that name no
+ * node (a stored value naming a removed node) kept at the end. `setValue` does not police
+ * disabled nodes (the widgets disable them); `toggle` refuses a disabled or unknown node with
+ * a warning, as useManyOfField does.
+ */
+export function useTreeField<T extends string = string, RouteId extends string = string, Ctx = any>(
+  opts: TreeFieldOptions<T, RouteId, Ctx>,
+  registry?: ErrorRoutesRegistry<RouteId>,
+): TreeFieldControls<T> {
+  const ctx = useFieldContext();
+  const nodes = resolveIn<TreeNode<T>[]>(opts.nodes, [], ctx, `Field '${opts.id}': option 'nodes'`);
+  const selection = opts.selection ?? 'topmost';
+
+  const inside = !opts.onChange && !opts.commit;
+  const initialValue = () => treeInitialValue<T>(opts, ctx, opts.id);
+  const field = useFieldCore<T[], T[], RouteId, Ctx>('tree', inside ? { ...opts, initialValue } : opts, registry);
+
+  // The same list object while it is already normalized, so the value is stable across renders.
+  const normalized = normalizeTreeValue(nodes, field.value, selection);
+  const value = sameList(normalized, field.value) ? field.value : normalized;
+
+  const checked = new Set(coveredNodes(nodes, value, selection));
+  const byValue = new Map<T, TreeNodeControls<T>>();
+  const control = (node: TreeNode<T>): TreeNodeControls<T> => {
+    const controls: TreeNodeControls<T> = { ...resolveChoice(opts.id, node), children: undefined, checked: checked.has(node.value) };
+    byValue.set(node.value, controls);
+    if (node.children) controls.children = node.children.map(control);
+    return controls;
+  };
+  const nodeControls = nodes.map(control);
+
+  const setValue = (next: T[]) => field.setValue(normalizeTreeValue(nodes, next, selection));
+
+  const toggle = (v: T) => {
+    const node = byValue.get(v);
+    if (!node) {
+      console.warn(`Field '${opts.id}': '${v}' is not one of its nodes`);
+      return;
+    }
+    if (!node.enabled) {
+      console.warn(`Field '${opts.id}': node '${v}' is disabled — ${node.whyDisabled ?? '(no reason)'}`);
+      return;
+    }
+    field.setValue(toggleTreeValue(nodes, value, v, selection));
+  };
+
+  return {
+    ...field,
+    value,
+    setValue,
+    nodes: nodeControls,
+    selection,
+    expandedKeys: expandedTreeKeys(nodes, value, opts.expand ?? 'top'),
+    byValue,
+    toggle,
+  };
+}